Update GA_offlinefixer.ps1 to v1.3

[Tony Mocanu (anmocanu)]

This script repairs a broken Azure Guest Agent by restoring registry keys and binaries from a rescue VM. It includes detailed steps for loading the SYSTEM hive, backing up, injecting service keys, and verifying the restoration process. .VERSION
v1.3: [May 2026] - Updated the script (current)
- Aligned nested VM detection with win-LKGC guard pattern.
- Skips Get-VM safely when Hyper-V module is unavailable.
v1.2: [May 2026] - Updated the script again (current)
- Fixed breaking exception when the Hyper-V module is not installed on the host.
- Added explicit checking via Get-Module before executing nested VM discovery.
v1.1: [May 2026] - Updated the script
- Included advanced Gen2 unlettered EFI fallback and dynamic drive-letter assignment.
v1.0: Initial commit. This was the version 1.0 of the script.

[EdwinBernal1]

Issues Found

🟡 Service disruption risk on rescue VM

Script force-stops WSearch and WinDefend and does not restore service state at end. On long-lived rescue hosts this can leave host security/indexing degraded after script completion.

Recommendation: capture original service states and restore them in finally.

🟡 Success can be reported even when fallback copy-back fails

When hive copy fallback ($hiveCopy) is used, copy-back to original hive happens in finally. If copy-back fails, error is logged, but disk can still remain in $fixedDisks, and overall script may still return success.

Recommendation: mark per-disk status failed if copy-back fails and exclude from success list.

[Tony Mocanu (anmocanu)]

addressed these feedbacks in the last commit aec8064

[EdwinBernal1]

Tony Mocanu (@anmocanu) could you help us with the review of these findings

Findings

Critical

File	Context	Issue	Recommendation
—	—	None (blocking)	—

Warning

File	Context	Issue	Recommendation
GA_offlinefixer.ps1	IMDS / telemetry	Introduces an outbound network call and collects VM SKU/Region/OS/hostname "for Application Insights correlation." IMDS is link-local (169.254.169.254) and non-routable, and the script only writes the values to the local log — but this is a new behavior for a repair script.	Confirm intent with owners; verify nothing is transmitted off-box. Per the repo's own security checklist (Network Calls / Data Exfiltration), document why the call is present. No PII beyond hostname/region/SKU.
GA_offlinefixer.ps1	Defender stop	Temporarily stops Windows Defender (WinDefend) and WSearch on the rescue VM. Restored in finally, but a hard kill (or crash before finally) could leave Defender stopped.	Prefer suspending indexing/handle locks without stopping Defender if possible; at minimum, ensure restoration is robust and logged.
GA_offlinefixer.ps1	disk cycling	Set-Disk -IsOffline on all non-rescue online disks broadens blast radius.	Scoped to non-rescue disks ($_.Number -ne $rescueDiskNum) — acceptable, but note in PR description.
GA_offlinefixer.ps1	version number	PR title says v1.3; top .VERSION entry is v1.4.	Reconcile.
GA_offlinefixer.ps1	xcopy exit code	Treats >= 2 as failure; xcopy returns 1 for "no files found," which would pass as success.	Confirm the copy source always has content; consider validating a non-empty copy.

Info

File	Context	Suggestion
GA_offlinefixer.ps1	backups	Both the registry hive and the WindowsAzure folder are backed up before replacement, and copy-back is verified — strong safety.
GA_offlinefixer.ps1	esentutl fallback	Locked-hive fallback via esentutl /y + copy-back is a good robustness addition; ensure copy-back only occurs after a successful unload (it does).
GA_offlinefixer.ps1	service key check	Verifies each service key exists on the rescue VM before export (avoids injecting missing keys on other OS versions). Good.

Operational Risk Assessment

Factor	Rating	Notes
Scope	Medium-High	Largest change; registry + binary replacement, service stop, disk cycling, network call.
Destructive ops	Medium	Registry injection + full WindowsAzure folder replacement — both backed up first.
Rollback possible	Partial	Hive backup + WindowsazurefaultyGAbackup folder exist; automatic restore is limited to hive copy-back path.
Testing documented	Yes (guide)	.SCENARIO_RECREATION/.VERIFICATION provided; confirm an actual run was performed.
Gen compatibility	Gen1+Gen2	Operates on lettered Windows volume; ControlSet logic generation-agnostic.

[Gabriela Limoli (glimoli)]

VMRepair Script Update: GA_offlinefixer.ps1

🎯 Summary

Comprehensive testing and validation of GA_offlinefixer.ps1 (v1.3) with fault injection verification across multiple VM configurations.

✅ Test Results

Overall Score: 78/100 (Grade: B)

Metric	Score	Status
Test Success Rate	12/12 passed (100%)	✅
Code Quality	96/100	✅
Header Validation	37/100	⚠️
Telemetry Coverage	20%	⚠️

🔬 Testing Performed

Strategy: Representative (6 OS configurations)
Fault Injection: ✅ Enabled with breaker script validation
Region: westus2
Test Date: 2026-08-10

Test Configurations

Configuration	OS	Gen	Storage	Fault Injected	Result
Modern Standard	Win2022	Gen2	Premium_LRS	✅ CORRUPTED	✅ FIXED
Legacy Support	Win2022	Gen1	Standard_LRS	✅ CORRUPTED	✅ FIXED
Encrypted Modern	Win2019	Gen2	Premium_LRS	✅ CORRUPTED	✅ FIXED
Cost-Optimized	Win2022	Gen2	Standard_LRS	✅ CORRUPTED	✅ FIXED
Latest Gen2 + Premium	Win2022	Gen2	Premium_LRS	✅ CORRUPTED	✅ FIXED
Mid-Tier 2016	Win2016	Gen2	StandardSSD_LRS	✅ CORRUPTED	✅ FIXED

Fault Injection Validation:

• Breaker Script: break-GA_offlinefixer.ps1
• Pre-repair state: ✅ Registry corruption verified (WindowsAzureGuestAgent and RdAgent keys deleted from SYSTEM hive)
• Post-repair state: ✅ [STATUS]::SUCCESS confirmed in all 6 configurations
• All 6 configurations passed fault injection testing

📊 Detailed Test Artifacts

Complete test artifacts available in SME work item:

• Interactive HTML Report: Full test execution details with fault injection validation
• Improvement Recommendations: Actionable enhancement suggestions
• Test Data Package: Complete logs, breaker scripts, validation outputs
• Reproducibility Guide: JSON manifest for test replication

🔗 SME Work Item: Tooling #59907 win-GA-fix

🚀 Improvements Implemented in v1.3

• Aligned nested VM detection with win-LKGC guard pattern
• Skips Get-VM safely when Hyper-V module is unavailable
• Uses the same partition discovery and collision handling as win-sac-onLatest
• Preserves Gen2 source GPT GUID during disk identity swap
• Stages and validates replacement files before moving existing Agent folder
• Rolls back Agent folder and SYSTEM hive after partial repair failures
• Bounds file-copy retries to avoid repair jobs appearing stuck

🧪 Validation Evidence

Pre-Repair State (Corrupted):

[BREAKER START: break-GA_offlinefixer.ps1]
DELETED HKLM:\SYSTEM\ControlSet001\Services\WindowsAzureGuestAgent
DELETED HKLM:\SYSTEM\ControlSet001\Services\RdAgent
Status: CORRUPTED ✅ Verified

Post-Repair State (Fixed):

[Info] Binary SYSTEM hive backup created and verified for F:
[Info] Loading SYSTEM hive from F: as BROKENSYSTEM_F...
[Info] Primary ControlSet identified: ControlSet001
[Info] Updating WindowsAzureGuestAgent in ControlSet001 on F:...
[Info] Updating WindowsAzureGuestAgent in backup ControlSet002 on F:...
[STATUS]::SUCCESS — VMAgent offline repair completed
Status: FIXED ✅ Verified

📋 Review Checklist

• Script tested with fault injection across 6 configurations
• Pre-repair corruption verified (registry keys deleted from SYSTEM hive)
• Post-repair fix verified ([STATUS]::SUCCESS in all configurations)
• Code quality: 96/100 (0 PSScriptAnalyzer errors, 0 warnings)
• Header validation improvements implemented (.DESCRIPTION and .NOTES missing — 37/100)
• Telemetry instrumentation added (20% coverage — Log-Start/Log-Success events missing)
• SME work item updated with test results
• Test artifacts attached

🔗 References

• SME Work Item: Tooling #59907
• Test Execution ID: GA_offlinefixer-20260810-200023
• Testing Framework: VMRepairMint
• Test Subscription: d4895902-76c8-43c7-be78-f27ef254ebeb

🙏 Request for Review

Please review the test results and improvement recommendations. The script is functionally sound (100% pass rate with fault injection), but would benefit from header documentation and telemetry improvements.

Priority Improvements:

1. ⚠️ Add .DESCRIPTION and .NOTES header blocks (currently 37/100 — required for automated documentation generation)
2. ⚠️ Add Log-Start/Log-Success structured events for Application Insights visibility (currently 20% telemetry coverage)