475 lines
14 KiB
Markdown
475 lines
14 KiB
Markdown
# WinDiagnostics
|
|
|
|
A dependency-free, non-GUI Windows diagnostics and maintenance-information collector written in PowerShell.
|
|
|
|
`WindowsMaintenanceReport.ps1` provides three levels of reporting:
|
|
|
|
* **Compact** — quick maintenance snapshot (`-Compact`)
|
|
* **Mid** — useful hardware, software, startup and driver inventory
|
|
* **Full** — comprehensive diagnostics, default (`-Full` is optional)
|
|
|
|
No Python, third-party PowerShell modules, or installation is required on the Windows machine.
|
|
|
|
## Quick Start
|
|
|
|
### Full report — Default
|
|
|
|
Open PowerShell and run:
|
|
|
|
```powershell
|
|
irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1' | iex
|
|
```
|
|
|
|
This downloads the latest version into memory and executes it without saving the script to disk.
|
|
|
|
The default report collects Full diagnostics. Use `-Compact` for a quick snapshot or `-Mid` for an inventory. Admin-only checks are skipped when PowerShell is not elevated.
|
|
|
|
For access to all available diagnostics, running PowerShell **as Administrator** is recommended.
|
|
|
|
## Report Levels
|
|
|
|
### Compact — Explicit opt-in
|
|
|
|
Retrieve the script and select `-Compact`:
|
|
|
|
```powershell
|
|
$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1'
|
|
& ([ScriptBlock]::Create($src)) -Compact
|
|
```
|
|
|
|
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
|
|
$src = irm 'https://proxy.dandaedre.com/gitea/Dandaedre/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1'
|
|
& ([ScriptBlock]::Create($src)) -Mid
|
|
```
|
|
|
|
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 — Default
|
|
|
|
Full runs when no mode switch is supplied. You can also request it explicitly:
|
|
|
|
```powershell
|
|
$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
|
|
|
|
Full also includes complete signed PnP and system driver inventories, Driver
|
|
Store packages, explicit Get-Disk and storage PnP enumeration, filesystem filters
|
|
and UpperFilters/LowerFilters registrations, all services, boot configuration,
|
|
enabled Windows features, Code Integrity events, reliability records, and crash
|
|
dump file metadata. Dump contents are not read.
|
|
|
|
Full mode is read-only and intended to collect evidence for troubleshooting. It does not automatically diagnose, repair, update, disable, uninstall or replace drivers or devices.
|
|
|
|
## Local Usage
|
|
|
|
If you already have the script, run Full diagnostics with:
|
|
|
|
```powershell
|
|
.\WindowsMaintenanceReport.ps1
|
|
```
|
|
|
|
Compact report:
|
|
|
|
```powershell
|
|
.\WindowsMaintenanceReport.ps1 -Compact
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
This applies `ExecutionPolicy Bypass` only to that PowerShell process and does not permanently modify the machine's execution policy.
|
|
|
|
## Options
|
|
|
|
### Report Mode
|
|
|
|
Omit the mode switch for Full diagnostics, or choose exactly one of `-Full`,
|
|
`-Mid`, or `-Compact`. Combining mode switches is an error.
|
|
|
|
View built-in help with `Get-Help .\WindowsMaintenanceReport.ps1 -Detailed`.
|
|
|
|
### Output Directory
|
|
|
|
Reports are saved in the current user's Documents folder by default, including when Windows redirects that folder to OneDrive or a network location.
|
|
|
|
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 Documents folder is unavailable or not writable, the script attempts to use the Windows temporary directory.
|
|
|
|
### Event Log History
|
|
|
|
The Full report includes recent Windows event history and reliability records.
|
|
|
|
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 events from each event log are included, newest first.
|
|
System and Application include Critical, Error and Warning events. Code Integrity
|
|
includes all levels. Repeated events are retained. Each event section records
|
|
`limit` and `truncated`; one extra event is requested to detect truncation.
|
|
|
|
For example:
|
|
|
|
```powershell
|
|
.\WindowsMaintenanceReport.ps1 -Full -EventLogDays 30 -MaxEventErrors 250
|
|
```
|
|
|
|
## Output
|
|
|
|
Collection progress is displayed in the terminal. The completed report is saved
|
|
as UTF-8 JSON without a BOM:
|
|
|
|
```text
|
|
windows_system_report_COMPUTERNAME_YYYYMMDD_HHMMSS.json
|
|
```
|
|
|
|
Schema version **2** introduces bounded event histories (including warnings),
|
|
new Full-mode inventories, and Compact collection-status metadata. The old
|
|
`recent_system_errors` and `recent_application_errors` sections are replaced by
|
|
`recent_system_events` and `recent_application_events`.
|
|
|
|
## Administrator Privileges
|
|
|
|
All three modes support non-administrator sessions. Admin-only checks (DISM,
|
|
SFC, filter enumeration, boot configuration and Windows optional features) are
|
|
marked `skipped`. Storage reliability counters also record an admin skip.
|
|
Other denied or unavailable checks are recorded and collection continues.
|
|
`host.administrator` records elevation; `warnings` describes limited access.
|
|
A writable output directory is still required.
|
|
|
|
Detailed sections contain `status`, `count`, `data` and `error`. Native command
|
|
failures retain executable, arguments, exit code and output. Full mode also
|
|
includes `diagnostic_collection`, with booleans derived from section status;
|
|
these indicate collection completeness, not system health. Compact retains
|
|
per-check status, count and error without duplicating its summary data.
|
|
|
|
## Read-Only Diagnostics
|
|
|
|
WinDiagnostics is designed to inspect the machine, not modify it.
|
|
|
|
It does **not**:
|
|
|
|
* 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 Full report can execute these diagnostic commands:
|
|
|
|
```cmd
|
|
DISM.exe /Online /Cleanup-Image /CheckHealth
|
|
```
|
|
|
|
and:
|
|
|
|
```cmd
|
|
sfc.exe /verifyonly
|
|
```
|
|
|
|
These inspect Windows health without automatically performing repairs.
|
|
|
|
WinDiagnostics deliberately does not automatically execute:
|
|
|
|
```cmd
|
|
DISM.exe /Online /Cleanup-Image /RestoreHealth
|
|
```
|
|
|
|
or:
|
|
|
|
```cmd
|
|
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 default Full 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 convenient syntax:
|
|
|
|
```powershell
|
|
irm 'URL' | iex
|
|
```
|
|
|
|
means:
|
|
|
|
* `irm` — `Invoke-RestMethod` downloads the script
|
|
* `iex` — `Invoke-Expression` executes the returned PowerShell code
|
|
|
|
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'
|
|
```
|
|
|
|
Then inspect it:
|
|
|
|
```powershell
|
|
notepad .\WindowsMaintenanceReport.ps1
|
|
```
|
|
|
|
and execute it afterward:
|
|
|
|
```powershell
|
|
.\WindowsMaintenanceReport.ps1
|
|
```
|
|
|
|
For higher-assurance environments, consider using a URL pinned to a specific repository commit rather than executing the current `main` branch.
|
|
|
|
## Privacy
|
|
|
|
Generated reports may contain information that should not be published publicly, including:
|
|
|
|
* Computer and Windows user names
|
|
* Hardware model and serial information
|
|
* Installed software
|
|
* Drivers
|
|
* Running processes
|
|
* Scheduled tasks
|
|
* Network configuration
|
|
* MAC addresses
|
|
* Local IP addresses
|
|
* DNS servers
|
|
* Event-log messages
|
|
|
|
Review Full reports before sharing them.
|
|
|
|
The Compact report intentionally exposes substantially less information than the Full report.
|
|
|
|
## Requirements
|
|
|
|
### Windows machine
|
|
|
|
* 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
|
|
# Full (default)
|
|
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'
|
|
|
|
# Compact
|
|
& ([ScriptBlock]::Create($src)) -Compact
|
|
|
|
# Mid
|
|
& ([ScriptBlock]::Create($src)) -Mid
|
|
|
|
# Full
|
|
& ([ScriptBlock]::Create($src)) -Full
|
|
|
|
# Local Full (default)
|
|
.\WindowsMaintenanceReport.ps1
|
|
|
|
# Local Compact
|
|
.\WindowsMaintenanceReport.ps1 -Compact
|
|
|
|
# Local Mid
|
|
.\WindowsMaintenanceReport.ps1 -Mid
|
|
|
|
# Local Full
|
|
.\WindowsMaintenanceReport.ps1 -Full
|
|
```
|
|
|
|
## Jenkins validation on FreeBSD
|
|
|
|
The `Jenkinsfile` runs static checks on a Jenkins agent labeled `freebsd`.
|
|
It parses tracked `.ps1`, `.psm1`, and `.psd1` files, runs PSScriptAnalyzer,
|
|
and checks for the structured JSON report markers. Parser and analyzer errors
|
|
fail the build; analyzer warnings are reported. The Windows diagnostics script
|
|
is never executed by CI, so these checks do not verify its Windows runtime behavior.
|
|
|
|
On the FreeBSD agent, install the native runtime and Git once as root:
|
|
|
|
```sh
|
|
pkg install git powershell
|
|
```
|
|
|
|
PowerShell is provided by the FreeBSD `shells/powershell` port. Use a FreeBSD
|
|
release and package repository that provides it. Linux PowerShell archives
|
|
are not native FreeBSD executables.
|
|
|
|
Configure the Jenkins node with the `freebsd` label and a working Jenkins agent
|
|
(Java and Git checkout). Ensure `/usr/local/bin` is on the agent service's PATH
|
|
for the initial checkout; the pipeline also adds it for its build steps.
|
|
Verify `pwsh -NoLogo -NoProfile -NonInteractive -Command '$PSVersionTable'`
|
|
as the Jenkins service user. No root access is needed during builds.
|
|
|
|
The agent needs HTTPS access to PowerShell Gallery and its download endpoints
|
|
when PSScriptAnalyzer is first saved. Modules are cached in `.tools/psmodules`
|
|
inside the writable workspace. The pipeline uses the installed PowerShell 7+
|
|
runtime rather than downloading a Linux binary. Jenkins needs Declarative
|
|
Pipeline and Timestamper support; the AnsiColor plugin is not required.
|
|
|
|
## Windows runtime validation
|
|
|
|
Run each command in both a normal and an elevated Windows PowerShell 5.1 session:
|
|
|
|
```powershell
|
|
.\WindowsMaintenanceReport.ps1
|
|
.\WindowsMaintenanceReport.ps1 -Compact
|
|
.\WindowsMaintenanceReport.ps1 -Mid
|
|
.\WindowsMaintenanceReport.ps1 -Full
|
|
.\WindowsMaintenanceReport.ps1 -Full -EventLogDays 30
|
|
```
|
|
|
|
For each returned path, validate JSON using `Get-Content -LiteralPath $path -Raw |
|
|
ConvertFrom-Json`. Check non-admin skips, unavailable sections, native exit codes,
|
|
event limits, and `diagnostic_collection`. Static CI checks cannot verify Windows
|
|
API availability or access permissions.
|