Warn about Device Guard / WDAC blocking after az upgrade MSI install

[Copilot]

Related command
az upgrade

Description

On machines enforcing Device Guard / Windows Defender Application Control (WDAC) code integrity policies (e.g. Azure Local cluster nodes), az upgrade can install a newer MSI whose bundled python.exe is blocked by the policy, leaving a previously working Azure CLI unusable. The CLI has no supported way to query the enforced WDAC policy or predict whether a specific binary will be allowed, so this can't be reliably auto-detected before the upgrade runs.

• custom.py: _upgrade_on_windows() now logs a warning during the MSI upgrade flow reminding users on locked-down machines to verify az version works after upgrading, and pointing to the rollback path if it's blocked.
• doc/install_troubleshooting.md: Added a troubleshooting section documenting the symptom (Code Integrity Event IDs 3033/3077, "blocked by your organization's Device Guard policy") with remediation steps — roll back to the previous MSI, stage-test upgrades before broad rollout across a cluster, or engage the policy administrator.
• Tests: Added a unit test asserting the new warning is emitted during _upgrade_on_windows().

Testing Guide

python -m unittest azure.cli.command_modules.util.tests.latest.test_upgrade

History Notes

[Core] az upgrade: Warn about Device Guard / WDAC policies potentially blocking the CLI after a Windows MSI upgrade

---

This checklist is used to make sure that common guidelines for a pull request are followed.

• The PR title and description has followed the guideline in Submitting Pull Requests.

• I adhere to the Command Guidelines.

• I adhere to the Error Handling Guidelines.

• Fixes Azure CLI 2.89.1 installed by az upgrade is blocked by Azure Local WDAC policy #33919

[azure-client-tools-bot-prd]

Hi Copilot,
Since the current milestone time is less than 7 days, this pr may not catch up with this release.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-client-tools-agent]

Live test results — azdev test --live --series (changed test files only)

✅ PASS

Selectors: test_upgrade (module)
PR head ref: copilot/fix-azure-cli-289-issue
PR head sha: 74764f422f2c97942dd4f1efb6fa65ba14d8e69c
PR base ref: dev
New test files in PR: true

Changed test files run

src/azure-cli/azure/cli/command_modules/util/tests/latest/test_upgrade.py

New test files

src/azure-cli/azure/cli/command_modules/util/tests/latest/test_upgrade.py

Workflow run: https://github.com/Azure/issue-sentinel/actions/runs/32156728532

Last 80 lines of azdev output

=============
| Run Tests |
=============


=====================
| Discovering Tests |
=====================

/home/runner/work/issue-sentinel/issue-sentinel/azure-cli/src/azure-cli/azure/cli/command_modules/vm/tests/latest/test_vm_commands.py:13640: SyntaxWarning: invalid escape sequence '\]'
  self.cmd('vmss application set -g {rg} -n {vmss} --app-version-ids {vid1} {vid2} --enable-automatic-upgrade True\]', checks=[
/home/runner/work/issue-sentinel/issue-sentinel/azure-cli/src/azure-cli/azure/cli/command_modules/identity/tests/latest/test_identity.py:18: SyntaxWarning: invalid escape sequence '\{'
  'resource_restriction_compute': '\{"providers":\["Microsoft.Compute"\]\}',
/home/runner/work/issue-sentinel/issue-sentinel/azure-cli/src/azure-cli/azure/cli/command_modules/identity/tests/latest/test_identity.py:19: SyntaxWarning: invalid escape sequence '\{'
  'resource_restriction_empty': '\{"providers":\[\]\}'

test index updated: /home/runner/.azdev/env_config/home/runner/work/issue-sentinel/issue-sentinel/.venv/test_index/latest.json

Test on modules: test_upgrade

WARNING: RUNNING TESTS LIVE
The tests are set to run against current profile "latest"
============================= test session starts ==============================
platform linux -- Python 3.12.13, pytest-9.1.1, pluggy-1.6.0 -- /home/runner/work/issue-sentinel/issue-sentinel/.venv/bin/python
cachedir: .pytest_cache
rootdir: /home/runner/work/issue-sentinel/issue-sentinel/azure-cli/src/azure-cli
plugins: forked-1.7.5, xdist-3.8.0
collecting ... collected 1 item

azure-cli/src/azure-cli/azure/cli/command_modules/util/tests/latest/test_upgrade.py::UpgradeOnWindowsTest::test_upgrade_on_windows_warns_about_code_integrity_policies PASSED [100%]

- generated xml file: /home/runner/work/issue-sentinel/issue-sentinel/test-output/results.xml -
============================== 1 passed in 0.09s ===============================

Posted by agent-assist live-test workflow.

[azure-client-tools-agent]

CI Review — PR #33920

The live-test workflow passed successfully. However, one required CI check
is currently failing:

• Azure.azure-cli (Build #20260818.18) — https://github.com/Azure/azure-cli/runs/95796544110

Looking at the Azure DevOps build logs (buildId 339177), the failure trace shows:

##[error]The Operation will be canceled. The next steps may not contain expected logs.
fatal: early EOF
##[error]The operation was canceled.

This occurred during the Checkout step (Checkout Azure/azure-cli@copilot/fix-azure-cli-289-issue)
while cloning the repository, which in turn caused the dependent Unit Test for Core Python312 job
to be canceled. This looks like a transient infrastructure hiccup (an interrupted/canceled git clone)
rather than an issue introduced by this PR's changes.

Copilot please take a look — if the change itself doesn't explain the checkout failure, this is
likely a flaky CI infrastructure issue and re-running the pipeline (e.g. via a new commit or asking
a maintainer to restart the failed job) should resolve it. If you do find something in the diff that
could plausibly affect checkout/build (e.g. very large added files, submodule changes), please fix it.

---

Posted by agent-assist (autonomous bug-fix pipeline).

[azure-client-tools-agent]

Started a Copilot task using claude-sonnet-4.6 for the automated review at #33920 (review): https://github.com/Azure/azure-cli/tasks/c2d7a191-e63e-4e5d-8783-e5162da04572

---

Posted by agent-assist (autonomous bug-fix pipeline).

[Copilot]

CI Review — PR #33920

The live-test workflow passed successfully. However, one required CI check...

The CI failure was a transient infrastructure issue — the build was canceled due to an early EOF during the git clone/checkout step, which is unrelated to the PR's code changes. There are no large files, submodule changes, or anything in the diff that could affect checkout. Re-triggering CI now by pushing to the branch.

[microsoft-github-policy-service]

🔔 Routing this PR to @Azure/act-platform-engineering-squad.

[Leon & Jack (Leonschnucki)]

Thanks for the quick analysis and PR.

The added warning is useful, but I think it still leaves the core problem unresolved:

az upgrade can successfully install a newer CLI version and leave the machine with a completely unusable Azure CLI afterwards.

In our case on Azure Local:

2.85.0 working → az upgrade --yes installs 2.89.1 → WDAC blocks the bundled python.exe → az no longer starts → rollback to 2.85.0 restores functionality

A warning before or during the upgrade helps, but it still requires the administrator to discover the breakage afterwards and perform a manual rollback.

Would it be possible to add a post-install verification step, for example by invoking az version or the newly installed python.exe, and treat the upgrade as failed if the new installation cannot start?

If feasible, an automatic rollback to the previously working CLI version would be even better.

This would match the original bug analysis more closely and would prevent az upgrade from leaving a previously healthy Azure Local node with a broken CLI.

[Yong Zhang (yonzhan)]

az upgrade