From bd6140bbba15f6f8f8bc978f56f119a07f4dea0f Mon Sep 17 00:00:00 2001 From: devanladdu Date: Mon, 1 Jun 2026 10:37:07 -0400 Subject: [PATCH 1/7] Add Manage-WindowsInstallerCache documentation Introduce docs/powershell/manage-windowsinstallercache.md describing the Manage-WindowsInstallerCache PowerShell utility. The document covers purpose, safety model, multi-layer validation sources (API, COM, registry, filesystem), process/functions, parameters, usage examples (dry-run, quarantine, restore, delete), logging/output, testing guidance, and an initial changelog entry (2026-06-01). --- .../manage-windowsinstallercache.md | 179 ++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 docs/powershell/manage-windowsinstallercache.md diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md new file mode 100644 index 000000000..e4ba48f51 --- /dev/null +++ b/docs/powershell/manage-windowsinstallercache.md @@ -0,0 +1,179 @@ +--- +id: 'fb30b46a-ae2e-498f-b049-48f687fea928' +slug: /fb30b46a-ae2e-498f-b049-48f687fea928 +title: 'Manage-WindowsInstallerCache' +title_meta: 'Manage-WindowsInstallerCache' +keywords: ['windows-installer', 'cache', 'msi', 'msp', 'quarantine', 'cleanup'] +description: 'Defensive Windows Installer cache reconciliation script with quarantine-first handling and rollback support.' +tags: ['windows', 'installer', 'maintenance', 'safety'] +draft: false +unlisted: false +last_update: + date: 2026-06-01 +--- + +## Description +`Manage-WindowsInstallerCache` is a defensive Windows Installer cache reconciliation utility for enterprise endpoints. + +It inspects `C:\Windows\Installer` by combining Windows Installer API data, the `WindowsInstaller.Installer` COM object, registry metadata, and filesystem reconciliation before anything is classified as removable. + +The default path is quarantine-first and scan-first (`WhatIf`). A file is only treated as a candidate when it is absent from every full-path validation source. + +## Safety Model +The script uses four validation layers before any file is marked as a candidate: + +1. Windows Installer API validation through an embedded C# wrapper. +2. COM validation through `WindowsInstaller.Installer`. +3. Registry validation across core Windows Installer metadata hives. +4. Filesystem reconciliation across `*.msi`, `*.msp`, and `*.mst` under `C:\Windows\Installer`. + +Classification rules: + +1. `SAFE_ORPHAN`: no full-path or weak reference was found and no collection errors were recorded. +2. `POSSIBLE_REFERENCE`: no full-path reference was found, but filename-only evidence was found in one or more sources. +3. `UNVERIFIED`: no reference was found, but one or more validation layers failed to enumerate cleanly. +4. `ACTIVE_REFERENCE`: the file was found in one or more full-path validation sources. + +Only `SAFE_ORPHAN` items are eligible for quarantine by default. + +`POSSIBLE_REFERENCE` and `UNVERIFIED` remain log-only unless `-Force` is explicitly used and confirmed. + +## Process +The script implements the following functions: + +1. `Get-InstallerReferences`: orchestrates API, COM, and registry collection. +2. `Get-MsiApiReferences`: uses the embedded C# wrapper to call MSI enumeration methods and collect `LocalPackage`, transform, and source-style metadata. +3. `Get-ComInstallerReferences`: uses `WindowsInstaller.Installer` to collect product and patch references. +4. `Get-RegistryInstallerReferences`: scans Windows Installer registry hives for cached package paths and transform references. +5. `Find-OrphanedInstallerFiles`: reconciles installer cache contents against collected references and applies risk classification. +6. `Move-InstallerCandidates`: quarantines candidate files and writes a rollback manifest. +7. `Restore-InstallerCandidates`: restores files from the rollback manifest. +8. `Write-CleanupLog`: writes structured JSON and CSV logs for change control and audits. + +The script does not rely on filesystem-only cleanup logic and does not direct-delete live cache files from the active installer directory. + +## Requirements +- PowerShell 5.1 or newer +- Local administrator rights +- Access to `C:\Windows\Installer` + +## Usage +Dry run scan (default behavior): + +```powershell +.\Manage-WindowsInstallerCache.ps1 -Verbose +``` + +Quarantine only verified orphaned files: + +```powershell +.\Manage-WindowsInstallerCache.ps1 -Quarantine -Verbose -Confirm +``` + +Delete previously quarantined files from a manifest: + +```powershell +.\Manage-WindowsInstallerCache.ps1 -Delete -ManifestPath .\Logs\Manage-WindowsInstallerCache-20260529-120001-manifest.json -Confirm +``` + +Restore quarantined files: + +```powershell +.\Manage-WindowsInstallerCache.ps1 -Restore -RestoreFromManifest .\Logs\Manage-WindowsInstallerCache-20260529-120001-manifest.json -Confirm +``` + +## Parameters +| Parameter | Required | Default | Description | +| --- | --- | --- | --- | +| `ScanOnly` | No | Active when no mode switch is supplied | Performs discovery and classification only. | +| `Quarantine` | No | `False` | Moves `SAFE_ORPHAN` findings into `C:\Windows\Installer\_Quarantine`. | +| `Delete` | No | `False` | Deletes previously quarantined files referenced by a manifest. | +| `Restore` | No | `False` | Restores previously quarantined files. | +| `RestoreFromManifest` | No | Newest manifest in log path | Manifest to restore from. | +| `ManifestPath` | No | Newest manifest in log path for delete mode | Manifest to delete from. | +| `InstallerPath` | No | `C:\Windows\Installer` | Root installer cache path to inspect. | +| `QuarantinePath` | No | `C:\Windows\Installer\_Quarantine` | Quarantine folder. | +| `LogPath` | No | `.\Logs` | Folder for JSON, CSV, and manifest files. | +| `Force` | No | `False` | Permits non-safe items to be processed after explicit confirmation. | + +## Safety Rationale +Every cleanup decision is intentionally conservative: + +1. The Windows Installer API is the primary path-based source of truth. +2. COM and registry results provide independent validation layers for servicing relationships not surfaced by one source. +3. Weak filename-only evidence never becomes a cleanup candidate and downgrades the item to `POSSIBLE_REFERENCE`. +4. Any validation collection failure downgrades otherwise unreferenced files to `UNVERIFIED`. +5. `Delete` operates against quarantine manifests, not the active installer cache, preserving a rollback window. + +## Output +The script writes: + +1. A JSON audit log with findings, actions, validation errors, and manifest references. +2. A CSV audit log suitable for ticket attachments or CAB evidence. +3. A rollback manifest whenever files are successfully quarantined. + +Default output location: + +```text +.\Logs\Manage-WindowsInstallerCache-.json +.\Logs\Manage-WindowsInstallerCache-.csv +.\Logs\Manage-WindowsInstallerCache--manifest.json +``` + +## Sample Dry-Run Output +```powershell +PS C:\> .\Manage-WindowsInstallerCache.ps1 -Verbose + +InstallerPath : C:\Windows\Installer +QuarantinePath : C:\Windows\Installer\_Quarantine +TotalFiles : 612 +SafeOrphans : 4 +PossibleReferences : 2 +Unverified : 0 +ActiveReferences : 606 +ValidationErrorCount : 0 +ManifestPath : +JsonLogPath : C:\Scripts\Manage-WindowsInstallerCache\Logs\Manage-WindowsInstallerCache-20260529-141500.json +CsvLogPath : C:\Scripts\Manage-WindowsInstallerCache\Logs\Manage-WindowsInstallerCache-20260529-141500.csv +``` + +## Testing +Pester tests can be added for classification and manifest workflows in a file such as: + +```text +Tests/Manage-WindowsInstallerCache.Tests.ps1 +``` + +## Testing Guide +The Windows Installer folder (`C:\Windows\Installer`) is hidden by default. Use the following steps to build a manual validation scenario. + +### Prepare File Explorer +1. Open File Explorer and navigate to `C:\Windows\Installer`. If the folder is not visible, enable hidden items or type the path directly. +2. Switch folder view to **Details**. +3. Right-click a column header and select **More...**. +4. Select **Subject** and **Authors**, then click **OK**. +5. Use these columns to identify which product owns each `.msi` or `.msp` file. + +### Create Orphaned Test Files +1. Install an application that uses Windows Installer (for example, Adobe Acrobat Reader). +2. After install, identify the new `*.msi` and `*.msp` files in `C:\Windows\Installer`. +3. Copy those files to a temporary folder such as `C:\Temp\InstallerBackup`. +4. Uninstall the application. +5. Paste the backed-up files back into `C:\Windows\Installer`. + +These reinserted files should now be orphaned because product references were removed during uninstall. + +### Run the Script +```powershell +.\Manage-WindowsInstallerCache.ps1 -Verbose +``` + +Expected result: +- Reinserted files are classified as `SAFE_ORPHAN` when all validation sources enumerate cleanly. +- Reinserted files are classified as `UNVERIFIED` if any validation source has collection errors. +- Still-active product files remain `ACTIVE_REFERENCE`. + +## Changelog + +### 2026-06-01 +- Initial version of the document From 04ba4162f3aff76269f57e76cfb6afe085865790 Mon Sep 17 00:00:00 2001 From: devanladdu Date: Wed, 3 Jun 2026 16:51:07 -0400 Subject: [PATCH 2/7] Update docs: default log path and tags Update Manage-WindowsInstallerCache docs to use new tag set (windows, disk-cleanup, installation, security) and change the default LogPath from .\Logs to C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache. Adjust example output and sample Json/Csv/manifest paths to reflect the centralized ProgramData Automation log location. --- docs/powershell/manage-windowsinstallercache.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md index e4ba48f51..8d9872173 100644 --- a/docs/powershell/manage-windowsinstallercache.md +++ b/docs/powershell/manage-windowsinstallercache.md @@ -5,7 +5,7 @@ title: 'Manage-WindowsInstallerCache' title_meta: 'Manage-WindowsInstallerCache' keywords: ['windows-installer', 'cache', 'msi', 'msp', 'quarantine', 'cleanup'] description: 'Defensive Windows Installer cache reconciliation script with quarantine-first handling and rollback support.' -tags: ['windows', 'installer', 'maintenance', 'safety'] +tags: ['windows', 'disk-cleanup', 'installation', 'security'] draft: false unlisted: false last_update: @@ -93,7 +93,7 @@ Restore quarantined files: | `ManifestPath` | No | Newest manifest in log path for delete mode | Manifest to delete from. | | `InstallerPath` | No | `C:\Windows\Installer` | Root installer cache path to inspect. | | `QuarantinePath` | No | `C:\Windows\Installer\_Quarantine` | Quarantine folder. | -| `LogPath` | No | `.\Logs` | Folder for JSON, CSV, and manifest files. | +| `LogPath` | No | `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` | Folder for JSON, CSV, and manifest files. | | `Force` | No | `False` | Permits non-safe items to be processed after explicit confirmation. | ## Safety Rationale @@ -115,9 +115,9 @@ The script writes: Default output location: ```text -.\Logs\Manage-WindowsInstallerCache-.json -.\Logs\Manage-WindowsInstallerCache-.csv -.\Logs\Manage-WindowsInstallerCache--manifest.json +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-.json +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-.csv +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache--manifest.json ``` ## Sample Dry-Run Output @@ -133,8 +133,8 @@ Unverified : 0 ActiveReferences : 606 ValidationErrorCount : 0 ManifestPath : -JsonLogPath : C:\Scripts\Manage-WindowsInstallerCache\Logs\Manage-WindowsInstallerCache-20260529-141500.json -CsvLogPath : C:\Scripts\Manage-WindowsInstallerCache\Logs\Manage-WindowsInstallerCache-20260529-141500.csv +JsonLogPath : C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-141500.json +CsvLogPath : C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-141500.csv ``` ## Testing From 1c4dc424ef1d97d946f861155aaeb20035189ef9 Mon Sep 17 00:00:00 2001 From: devanladdu Date: Fri, 5 Jun 2026 16:10:47 -0400 Subject: [PATCH 3/7] Streamline Manage-WindowsInstallerCache docs Refactor and condense the Manage-WindowsInstallerCache documentation for clarity and brevity. Updated the top-level description to focus on safe identification and quarantine of orphaned installer files, replaced the verbose safety-model and process sections with a concise overview, and converted the Parameters list into a compact table including types. Clarified usage examples, simplified the Outputs section and default log location, removed sample dry-run output and the detailed testing guide, and updated the changelog. Documentation-only changes; no code or behavioral changes. --- .../manage-windowsinstallercache.md | 147 +++--------------- 1 file changed, 25 insertions(+), 122 deletions(-) diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md index 8d9872173..21d91f6a6 100644 --- a/docs/powershell/manage-windowsinstallercache.md +++ b/docs/powershell/manage-windowsinstallercache.md @@ -4,7 +4,7 @@ slug: /fb30b46a-ae2e-498f-b049-48f687fea928 title: 'Manage-WindowsInstallerCache' title_meta: 'Manage-WindowsInstallerCache' keywords: ['windows-installer', 'cache', 'msi', 'msp', 'quarantine', 'cleanup'] -description: 'Defensive Windows Installer cache reconciliation script with quarantine-first handling and rollback support.' +description: 'Safely identifies and quarantines orphaned files in the Windows Installer cache to reclaim disk space.' tags: ['windows', 'disk-cleanup', 'installation', 'security'] draft: false unlisted: false @@ -13,64 +13,30 @@ last_update: --- ## Description -`Manage-WindowsInstallerCache` is a defensive Windows Installer cache reconciliation utility for enterprise endpoints. -It inspects `C:\Windows\Installer` by combining Windows Installer API data, the `WindowsInstaller.Installer` COM object, registry metadata, and filesystem reconciliation before anything is classified as removable. - -The default path is quarantine-first and scan-first (`WhatIf`). A file is only treated as a candidate when it is absent from every full-path validation source. - -## Safety Model -The script uses four validation layers before any file is marked as a candidate: - -1. Windows Installer API validation through an embedded C# wrapper. -2. COM validation through `WindowsInstaller.Installer`. -3. Registry validation across core Windows Installer metadata hives. -4. Filesystem reconciliation across `*.msi`, `*.msp`, and `*.mst` under `C:\Windows\Installer`. - -Classification rules: - -1. `SAFE_ORPHAN`: no full-path or weak reference was found and no collection errors were recorded. -2. `POSSIBLE_REFERENCE`: no full-path reference was found, but filename-only evidence was found in one or more sources. -3. `UNVERIFIED`: no reference was found, but one or more validation layers failed to enumerate cleanly. -4. `ACTIVE_REFERENCE`: the file was found in one or more full-path validation sources. - -Only `SAFE_ORPHAN` items are eligible for quarantine by default. - -`POSSIBLE_REFERENCE` and `UNVERIFIED` remain log-only unless `-Force` is explicitly used and confirmed. - -## Process -The script implements the following functions: - -1. `Get-InstallerReferences`: orchestrates API, COM, and registry collection. -2. `Get-MsiApiReferences`: uses the embedded C# wrapper to call MSI enumeration methods and collect `LocalPackage`, transform, and source-style metadata. -3. `Get-ComInstallerReferences`: uses `WindowsInstaller.Installer` to collect product and patch references. -4. `Get-RegistryInstallerReferences`: scans Windows Installer registry hives for cached package paths and transform references. -5. `Find-OrphanedInstallerFiles`: reconciles installer cache contents against collected references and applies risk classification. -6. `Move-InstallerCandidates`: quarantines candidate files and writes a rollback manifest. -7. `Restore-InstallerCandidates`: restores files from the rollback manifest. -8. `Write-CleanupLog`: writes structured JSON and CSV logs for change control and audits. - -The script does not rely on filesystem-only cleanup logic and does not direct-delete live cache files from the active installer directory. +Identifies orphaned `.msi`, `.msp`, and `.mst` files in `C:\Windows\Installer` and safely quarantines them to reclaim disk space. Files are validated against multiple sources before removal. The default mode is scan-only — no files are moved or deleted without explicit action. ## Requirements + - PowerShell 5.1 or newer - Local administrator rights - Access to `C:\Windows\Installer` ## Usage -Dry run scan (default behavior): + +Scan and classify files (default, no changes made): ```powershell .\Manage-WindowsInstallerCache.ps1 -Verbose ``` -Quarantine only verified orphaned files: +Quarantine verified orphaned files: ```powershell .\Manage-WindowsInstallerCache.ps1 -Quarantine -Verbose -Confirm ``` -Delete previously quarantined files from a manifest: +Delete previously quarantined files: ```powershell .\Manage-WindowsInstallerCache.ps1 -Delete -ManifestPath .\Logs\Manage-WindowsInstallerCache-20260529-120001-manifest.json -Confirm @@ -83,97 +49,34 @@ Restore quarantined files: ``` ## Parameters -| Parameter | Required | Default | Description | -| --- | --- | --- | --- | -| `ScanOnly` | No | Active when no mode switch is supplied | Performs discovery and classification only. | -| `Quarantine` | No | `False` | Moves `SAFE_ORPHAN` findings into `C:\Windows\Installer\_Quarantine`. | -| `Delete` | No | `False` | Deletes previously quarantined files referenced by a manifest. | -| `Restore` | No | `False` | Restores previously quarantined files. | -| `RestoreFromManifest` | No | Newest manifest in log path | Manifest to restore from. | -| `ManifestPath` | No | Newest manifest in log path for delete mode | Manifest to delete from. | -| `InstallerPath` | No | `C:\Windows\Installer` | Root installer cache path to inspect. | -| `QuarantinePath` | No | `C:\Windows\Installer\_Quarantine` | Quarantine folder. | -| `LogPath` | No | `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` | Folder for JSON, CSV, and manifest files. | -| `Force` | No | `False` | Permits non-safe items to be processed after explicit confirmation. | - -## Safety Rationale -Every cleanup decision is intentionally conservative: - -1. The Windows Installer API is the primary path-based source of truth. -2. COM and registry results provide independent validation layers for servicing relationships not surfaced by one source. -3. Weak filename-only evidence never becomes a cleanup candidate and downgrades the item to `POSSIBLE_REFERENCE`. -4. Any validation collection failure downgrades otherwise unreferenced files to `UNVERIFIED`. -5. `Delete` operates against quarantine manifests, not the active installer cache, preserving a rollback window. + +| Parameter | Required | Default | Type | Description | +| --- | --- | --- | --- | --- | +| `ScanOnly` | No | Active when no mode switch is supplied | Switch | Performs discovery and classification only. | +| `Quarantine` | No | `False` | Switch | Moves verified orphaned files to the quarantine folder. | +| `Delete` | No | `False` | Switch | Deletes previously quarantined files referenced by a manifest. | +| `Restore` | No | `False` | Switch | Restores previously quarantined files from a manifest. | +| `RestoreFromManifest` | No | Newest manifest in log path | String | Path to the manifest used for restore. | +| `ManifestPath` | No | Newest manifest in log path | String | Path to the manifest used for delete. | +| `InstallerPath` | No | `C:\Windows\Installer` | String | Root installer cache path to inspect. | +| `QuarantinePath` | No | `C:\Windows\Installer\_Quarantine` | String | Quarantine destination folder. | +| `LogPath` | No | `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` | String | Folder for JSON, CSV, and manifest output. | +| `Force` | No | `False` | Switch | Permits non-safe items to be processed after explicit confirmation. | ## Output -The script writes: -1. A JSON audit log with findings, actions, validation errors, and manifest references. -2. A CSV audit log suitable for ticket attachments or CAB evidence. -3. A rollback manifest whenever files are successfully quarantined. +- JSON audit log +- CSV audit log (suitable for ticket attachments) +- Rollback manifest (created when files are quarantined) Default output location: ```text -C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-.json -C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-.csv -C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache--manifest.json -``` - -## Sample Dry-Run Output -```powershell -PS C:\> .\Manage-WindowsInstallerCache.ps1 -Verbose - -InstallerPath : C:\Windows\Installer -QuarantinePath : C:\Windows\Installer\_Quarantine -TotalFiles : 612 -SafeOrphans : 4 -PossibleReferences : 2 -Unverified : 0 -ActiveReferences : 606 -ValidationErrorCount : 0 -ManifestPath : -JsonLogPath : C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-141500.json -CsvLogPath : C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-141500.csv -``` - -## Testing -Pester tests can be added for classification and manifest workflows in a file such as: - -```text -Tests/Manage-WindowsInstallerCache.Tests.ps1 +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\ ``` -## Testing Guide -The Windows Installer folder (`C:\Windows\Installer`) is hidden by default. Use the following steps to build a manual validation scenario. - -### Prepare File Explorer -1. Open File Explorer and navigate to `C:\Windows\Installer`. If the folder is not visible, enable hidden items or type the path directly. -2. Switch folder view to **Details**. -3. Right-click a column header and select **More...**. -4. Select **Subject** and **Authors**, then click **OK**. -5. Use these columns to identify which product owns each `.msi` or `.msp` file. - -### Create Orphaned Test Files -1. Install an application that uses Windows Installer (for example, Adobe Acrobat Reader). -2. After install, identify the new `*.msi` and `*.msp` files in `C:\Windows\Installer`. -3. Copy those files to a temporary folder such as `C:\Temp\InstallerBackup`. -4. Uninstall the application. -5. Paste the backed-up files back into `C:\Windows\Installer`. - -These reinserted files should now be orphaned because product references were removed during uninstall. - -### Run the Script -```powershell -.\Manage-WindowsInstallerCache.ps1 -Verbose -``` - -Expected result: -- Reinserted files are classified as `SAFE_ORPHAN` when all validation sources enumerate cleanly. -- Reinserted files are classified as `UNVERIFIED` if any validation source has collection errors. -- Still-active product files remain `ACTIVE_REFERENCE`. - ## Changelog ### 2026-06-01 + - Initial version of the document From 3af50f2504d790347b56a04cb2b242b8db340c80 Mon Sep 17 00:00:00 2001 From: Rj98-sh Date: Mon, 8 Jun 2026 12:54:45 -0400 Subject: [PATCH 4/7] Update manage-windowsinstallercache.md --- docs/powershell/manage-windowsinstallercache.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md index 21d91f6a6..b824c1d23 100644 --- a/docs/powershell/manage-windowsinstallercache.md +++ b/docs/powershell/manage-windowsinstallercache.md @@ -9,12 +9,12 @@ tags: ['windows', 'disk-cleanup', 'installation', 'security'] draft: false unlisted: false last_update: - date: 2026-06-01 + date: 2026-06-08 --- ## Description -Identifies orphaned `.msi`, `.msp`, and `.mst` files in `C:\Windows\Installer` and safely quarantines them to reclaim disk space. Files are validated against multiple sources before removal. The default mode is scan-only — no files are moved or deleted without explicit action. +Identifies orphaned `.msi`, `.msp`, and `.mst` files in `C:\Windows\Installer` and safely quarantines them to reclaim disk space. Files are validated against multiple sources before removal. The default mode is scan-only and no files are moved or deleted without explicit action. ## Requirements @@ -77,6 +77,6 @@ C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\ ## Changelog -### 2026-06-01 +### 2026-06-08 - Initial version of the document From 2646dd6695452671276691ce7c8f230442e50b42 Mon Sep 17 00:00:00 2001 From: devanladdu Date: Mon, 8 Jun 2026 13:47:37 -0400 Subject: [PATCH 5/7] Docs: Update Manage-WindowsInstallerCache paths Update Manage-WindowsInstallerCache documentation: bump last_update to 2026-06-08, replace relative example manifest paths with the absolute LogPath, clarify the ManifestPath parameter (how manifests are produced and used), mention the default Quarantine folder in the parameter table, and add a changelog entry noting the corrected LogPath default. --- docs/powershell/manage-windowsinstallercache.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md index 21d91f6a6..b330b906e 100644 --- a/docs/powershell/manage-windowsinstallercache.md +++ b/docs/powershell/manage-windowsinstallercache.md @@ -9,7 +9,7 @@ tags: ['windows', 'disk-cleanup', 'installation', 'security'] draft: false unlisted: false last_update: - date: 2026-06-01 + date: 2026-06-08 --- ## Description @@ -39,13 +39,13 @@ Quarantine verified orphaned files: Delete previously quarantined files: ```powershell -.\Manage-WindowsInstallerCache.ps1 -Delete -ManifestPath .\Logs\Manage-WindowsInstallerCache-20260529-120001-manifest.json -Confirm +.\Manage-WindowsInstallerCache.ps1 -Delete -ManifestPath "C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-120001-manifest.json" -Confirm ``` Restore quarantined files: ```powershell -.\Manage-WindowsInstallerCache.ps1 -Restore -RestoreFromManifest .\Logs\Manage-WindowsInstallerCache-20260529-120001-manifest.json -Confirm +.\Manage-WindowsInstallerCache.ps1 -Restore -RestoreFromManifest "C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-120001-manifest.json" -Confirm ``` ## Parameters @@ -53,11 +53,11 @@ Restore quarantined files: | Parameter | Required | Default | Type | Description | | --- | --- | --- | --- | --- | | `ScanOnly` | No | Active when no mode switch is supplied | Switch | Performs discovery and classification only. | -| `Quarantine` | No | `False` | Switch | Moves verified orphaned files to the quarantine folder. | +| `Quarantine` | No | `False` | Switch | Moves verified orphaned files to the quarantine folder (`C:\Windows\Installer\_Quarantine` by default). | | `Delete` | No | `False` | Switch | Deletes previously quarantined files referenced by a manifest. | | `Restore` | No | `False` | Switch | Restores previously quarantined files from a manifest. | | `RestoreFromManifest` | No | Newest manifest in log path | String | Path to the manifest used for restore. | -| `ManifestPath` | No | Newest manifest in log path | String | Path to the manifest used for delete. | +| `ManifestPath` | No | Newest manifest in log path | String | Path to the manifest produced by a `-Quarantine` run. The manifest is created automatically when at least one file is quarantined — it records each file's original path, quarantine destination, hash, and classification. Supply this path to `-Delete` or `-Restore`. | | `InstallerPath` | No | `C:\Windows\Installer` | String | Root installer cache path to inspect. | | `QuarantinePath` | No | `C:\Windows\Installer\_Quarantine` | String | Quarantine destination folder. | | `LogPath` | No | `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` | String | Folder for JSON, CSV, and manifest output. | @@ -77,6 +77,10 @@ C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\ ## Changelog +### 2026-06-08 + +- Fixed `LogPath` default from `.\Logs` to `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` + ### 2026-06-01 - Initial version of the document From b802c5565b1cebdac4955a7be6910f166094f472 Mon Sep 17 00:00:00 2001 From: Rj98-sh Date: Tue, 9 Jun 2026 07:56:12 -0400 Subject: [PATCH 6/7] Update manage-windowsinstallercache.md --- docs/powershell/manage-windowsinstallercache.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md index e4fcaea29..c6db3fcf5 100644 --- a/docs/powershell/manage-windowsinstallercache.md +++ b/docs/powershell/manage-windowsinstallercache.md @@ -79,8 +79,4 @@ C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\ ### 2026-06-08 -- Fixed `LogPath` default from `.\Logs` to `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` - -### 2026-06-01 - - Initial version of the document From 4351f2b513ff284e7cfc31d043df04adb5bcb0f2 Mon Sep 17 00:00:00 2001 From: devanladdu Date: Tue, 9 Jun 2026 12:26:53 -0400 Subject: [PATCH 7/7] docs: expand usage, classifications, and outputs Update Manage-WindowsInstallerCache documentation to clarify validation and safety behavior. Changes include: - Expanded Description to list validation sources (Windows Installer API, COM object, and registry) and emphasize scan-only default. - Renamed scan usage to "Dry-run scan" and removed interactive `-Confirm` flags from examples; added `-Force` example to quarantine unverified items. - Added a File Classifications table (SAFE_ORPHAN, POSSIBLE_REFERENCE, UNVERIFIED, ACTIVE_REFERENCE) and explained quarantine eligibility. - Improved parameter descriptions (Quarantine, Delete, Restore, ManifestPath, Force) and listed exact output artifacts and paths. - Added sample output and a changelog entry (2026-06-09) documenting the doc updates. These edits aim to make the tool's safety model, CLI examples, and produced artifacts clearer for operators. --- .../manage-windowsinstallercache.md | 70 +++++++++++++++---- 1 file changed, 57 insertions(+), 13 deletions(-) diff --git a/docs/powershell/manage-windowsinstallercache.md b/docs/powershell/manage-windowsinstallercache.md index e4fcaea29..ad92cf6c4 100644 --- a/docs/powershell/manage-windowsinstallercache.md +++ b/docs/powershell/manage-windowsinstallercache.md @@ -14,7 +14,7 @@ last_update: ## Description -Identifies orphaned `.msi`, `.msp`, and `.mst` files in `C:\Windows\Installer` and safely quarantines them to reclaim disk space. Files are validated against multiple sources before removal. The default mode is scan-only and no files are moved or deleted without explicit action. +Identifies orphaned `.msi`, `.msp`, and `.mst` files in `C:\Windows\Installer` and safely quarantines them to reclaim disk space. The script validates files against the Windows Installer API, the `WindowsInstaller.Installer` COM object, and registry metadata before classifying anything as removable. The default mode is scan-only — no files are moved or deleted without explicit action. ## Requirements @@ -24,7 +24,7 @@ Identifies orphaned `.msi`, `.msp`, and `.mst` files in `C:\Windows\Installer` a ## Usage -Scan and classify files (default, no changes made): +Dry-run scan (default, no changes made): ```powershell .\Manage-WindowsInstallerCache.ps1 -Verbose @@ -33,50 +33,94 @@ Scan and classify files (default, no changes made): Quarantine verified orphaned files: ```powershell -.\Manage-WindowsInstallerCache.ps1 -Quarantine -Verbose -Confirm +.\Manage-WindowsInstallerCache.ps1 -Quarantine -Verbose +``` + +Quarantine orphaned and unverified files without prompting: + +```powershell +.\Manage-WindowsInstallerCache.ps1 -Quarantine -Force ``` Delete previously quarantined files: ```powershell -.\Manage-WindowsInstallerCache.ps1 -Delete -ManifestPath "C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-120001-manifest.json" -Confirm +.\Manage-WindowsInstallerCache.ps1 -Delete -ManifestPath "C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-120001-manifest.json" ``` Restore quarantined files: ```powershell -.\Manage-WindowsInstallerCache.ps1 -Restore -RestoreFromManifest "C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-120001-manifest.json" -Confirm +.\Manage-WindowsInstallerCache.ps1 -Restore -RestoreFromManifest "C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-120001-manifest.json" ``` +## File Classifications + +Each file in the installer cache receives one of the following classifications: + +| Classification | Meaning | Eligible for Quarantine | +| --- | --- | --- | +| `SAFE_ORPHAN` | No full-path or weak reference found; all validation sources enumerated cleanly. | Yes (default) | +| `POSSIBLE_REFERENCE` | No full-path reference found, but filename-only evidence exists in one or more sources. | No | +| `UNVERIFIED` | No reference found, but one or more validation layers failed to enumerate cleanly. | Only with `-Force` or operator confirmation | +| `ACTIVE_REFERENCE` | File found in one or more full-path validation sources. | No | + ## Parameters | Parameter | Required | Default | Type | Description | | --- | --- | --- | --- | --- | | `ScanOnly` | No | Active when no mode switch is supplied | Switch | Performs discovery and classification only. | -| `Quarantine` | No | `False` | Switch | Moves verified orphaned files to the quarantine folder (`C:\Windows\Installer\_Quarantine` by default). | -| `Delete` | No | `False` | Switch | Deletes previously quarantined files referenced by a manifest. | -| `Restore` | No | `False` | Switch | Restores previously quarantined files from a manifest. | +| `Quarantine` | No | `False` | Switch | Moves `SAFE_ORPHAN` files to the quarantine folder (`C:\Windows\Installer\_Quarantine` by default). | +| `Delete` | No | `False` | Switch | Permanently deletes previously quarantined files referenced by a manifest. | +| `Restore` | No | `False` | Switch | Restores previously quarantined files from a manifest back to their original location. | | `RestoreFromManifest` | No | Newest manifest in log path | String | Path to the manifest used for restore. | -| `ManifestPath` | No | Newest manifest in log path | String | Path to the manifest produced by a `-Quarantine` run. The manifest is created automatically when at least one file is quarantined — it records each file's original path, quarantine destination, hash, and classification. Supply this path to `-Delete` or `-Restore`. | +| `ManifestPath` | No | Newest manifest in log path | String | Path to the manifest produced by a `-Quarantine` run. Created automatically when at least one file is quarantined — records each file's original path, quarantine destination, hash, size, classification, and timestamp. Supply this path to `-Delete` or `-Restore`. | | `InstallerPath` | No | `C:\Windows\Installer` | String | Root installer cache path to inspect. | | `QuarantinePath` | No | `C:\Windows\Installer\_Quarantine` | String | Quarantine destination folder. | | `LogPath` | No | `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache` | String | Folder for JSON, CSV, and manifest output. | -| `Force` | No | `False` | Switch | Permits non-safe items to be processed after explicit confirmation. | +| `Force` | No | `False` | Switch | Suppresses confirmation prompts for `UNVERIFIED` files during quarantine, quarantining them automatically. | ## Output -- JSON audit log -- CSV audit log (suitable for ticket attachments) +The script writes: + +- JSON audit log with findings, actions, validation errors, and manifest references +- CSV audit log (suitable for ticket attachments or CAB evidence) +- Scan report CSV with per-file classification details (scan and quarantine modes) - Rollback manifest (created when files are quarantined) Default output location: ```text -C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\ +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-.json +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-.csv +C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache--manifest.json +``` + +## Sample Output + +```powershell +PS C:\> .\Manage-WindowsInstallerCache.ps1 -Verbose + +InstallerPath : C:\Windows\Installer +QuarantinePath : C:\Windows\Installer\_Quarantine +TotalFiles : 612 +SafeOrphans : 4 +PossibleReferences : 2 +Unverified : 0 +ActiveReferences : 606 +ValidationErrorCount : 0 +ManifestPath : +JsonLogPath : C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-141500.json +CsvLogPath : C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache\Manage-WindowsInstallerCache-20260529-141500.csv ``` ## Changelog +### 2026-06-09 + +- Updated documentation to reflect classification model and safety details + ### 2026-06-08 - Fixed `LogPath` default from `.\Logs` to `C:\ProgramData\_Automation\Script\Manage-WindowsInstallerCache`