├── what-if-noise.PNG ├── CODE_OF_CONDUCT.md ├── .github ├── ISSUE_TEMPLATE │ ├── other-bug.md │ └── what-if-noise-report.md └── fabricbot.json ├── LICENSE ├── storage-output.json ├── InstallModules.md ├── SECURITY.md └── README.md /what-if-noise.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Azure/arm-template-whatif/HEAD/what-if-noise.PNG -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Microsoft Open Source Code of Conduct 2 | 3 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 4 | 5 | Resources: 6 | 7 | - [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) 8 | - [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 9 | - Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns 10 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/other-bug.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Other bug 3 | about: Could be issues with the diff output or other usability issues 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Client** [e.g. PowerShell, CLI, API) 27 | 28 | **Additional context** 29 | Add any other context about the problem here. 30 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/what-if-noise-report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: What-If Noise report 3 | about: Tell us about the noise you encountered when using what-if 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Describe the noise 11 | 12 | **Resource type** (i.e. Microsoft.Storage/storageAccounts) 13 | 14 | **apiVersion** (i.e. 2019-04-01) 15 | 16 | **Client (PowerShell, Azure CLI, or API)** 17 | 18 | **Relevant ARM Template code (we only need the resource object for the above `resourceType` and `apiVersion`, but if it's easier you can include the entire template** 19 | 20 | **Expected response (i.e. "I expected no noise since the template has not been modified since the resources were deployed)** 21 | 22 | **Current (noisy) response (either include a screenshot of the what-if output, or copy/paste the text)** 23 | 24 | 25 | 26 | **Additional context** 27 | Add any other context about the problem here. 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Microsoft Corporation. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE 22 | -------------------------------------------------------------------------------- /storage-output.json: -------------------------------------------------------------------------------- 1 | { 2 | "sku": { 3 | "name": "Standard_LRS", 4 | "tier": "Standard" 5 | }, 6 | "kind": "Storage", 7 | "id": "/subscriptions/e93d3ee6-fac1-412f-92d6-bfb379e81af2/resourceGroups/test-005/providers/Microsoft.Storage/storageAccounts/storagedczol7xfovaoe", 8 | "name": "storagedczol7xfovaoe", 9 | "type": "Microsoft.Storage/storageAccounts", 10 | "location": "eastus", 11 | "tags": {}, 12 | "properties": { 13 | "networkAcls": { 14 | "bypass": "AzureServices", 15 | "virtualNetworkRules": [], 16 | "ipRules": [], 17 | "defaultAction": "Allow" 18 | }, 19 | "supportsHttpsTrafficOnly": true, 20 | "encryption": { 21 | "services": { 22 | "file": { 23 | "enabled": true, 24 | "lastEnabledTime": "2019-11-11T23:54:22.6182369Z" 25 | }, 26 | "blob": { 27 | "enabled": true, 28 | "lastEnabledTime": "2019-11-11T23:54:22.6182369Z" 29 | } 30 | }, 31 | "keySource": "Microsoft.Storage" 32 | }, 33 | "provisioningState": "Succeeded", 34 | "creationTime": "2019-11-11T23:54:22.5713478Z", 35 | "primaryEndpoints": { 36 | "blob": "https://storagedczol7xfovaoe.blob.core.windows.net/", 37 | "queue": "https://storagedczol7xfovaoe.queue.core.windows.net/", 38 | "table": "https://storagedczol7xfovaoe.table.core.windows.net/", 39 | "file": "https://storagedczol7xfovaoe.file.core.windows.net/" 40 | }, 41 | "primaryLocation": "eastus", 42 | "statusOfPrimary": "available" 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /InstallModules.md: -------------------------------------------------------------------------------- 1 | # Instructions to install the what-if PS module 2 | * Make sure you have access to https://dev.azure.com/AzDeploymentWhatIf/WhatIfModules 3 | * Create a [PAT (Personal Access Token)](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops) to get command-line access to Azure DevOps Services 4 | * Open PowerShell as administrator 5 | * Run the following commands: 6 | 7 | ```PowerShell 8 | $password = ConvertTo-SecureString "YOUR PAT FROM THE CREATING THE PREVIOUS STEP" -AsPlainText -Force 9 | ``` 10 | 11 | 12 | ```PowerShell 13 | $credential = New-Object System.Management.Automation.PSCredential "YOUR EMAIL FOR AZURE DEVOPS SERVICES", $password 14 | ``` 15 | 16 | ```PowerShell 17 | Register-PSRepository -Name WhatIfRepository -SourceLocation https://pkgs.dev.azure.com/AzDeploymentWhatIf/WhatIfModules/_packaging/WhatIfFeed/nuget/v2 -PackageManagementProvider Nuget -InstallationPolicy Trusted -Credential $credential 18 | ``` 19 | 20 | ```PowerShell 21 | Install-Module -Name Az.Resources -Repository WhatIfRepository -RequiredVersion 2.0.1-alpha5 -AllowPrerelease -AllowClobber -Credential $credential -SkipPublisherCheck 22 | ``` 23 | 24 | * If you want to switch back to another installed version, simply run: 25 | ```PowerShell 26 | Import-Module Az.Resources -RequiredVersion 27 | ``` 28 | 29 | * To check if there's a newer version, do: 30 | ```PowerShell 31 | Find-Module -Name Az.Resources -Repository WhatIfRepository -AllVersions -AllowPrerelease -Credential $credential 32 | ``` 33 | 34 | * If you are done testing the package, you may uninstall it by running: 35 | ```PowerShell 36 | Uninstall-Module -Name Az.Resources -RequiredVersion 2.0.1-alpha5 -AllowPrerelease 37 | ``` 38 | 39 | ## Known issue 40 | If you are using the default version of the `PowerShellGet` module, you may encounter `Unable to resolve package resource` error when running the commands above. You can fix it by updating `PowerShellGet` to the newest version: 41 | 42 | ``` 43 | Uninstall-Module PowershellGet 44 | Install-Module PowerShellGet -Force 45 | ``` 46 | 47 | Once the update is done, restart your PowerShell session and you should be able to install the What-If module. 48 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)) of a security vulnerability, please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://microsoft.com/msrc/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /.github/fabricbot.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "1.0", 3 | "tasks": [ 4 | { 5 | "taskType": "trigger", 6 | "capabilityId": "IssueResponder", 7 | "subCapability": "IssuesOnlyResponder", 8 | "version": "1.0", 9 | "id": "r-15QIs55", 10 | "config": { 11 | "conditions": { 12 | "operator": "and", 13 | "operands": [ 14 | { 15 | "name": "isAction", 16 | "parameters": { 17 | "action": "opened" 18 | } 19 | }, 20 | { 21 | "operator": "not", 22 | "operands": [ 23 | { 24 | "name": "isPartOfProject", 25 | "parameters": {} 26 | } 27 | ] 28 | }, 29 | { 30 | "operator": "not", 31 | "operands": [ 32 | { 33 | "name": "isAssignedToSomeone", 34 | "parameters": {} 35 | } 36 | ] 37 | } 38 | ] 39 | }, 40 | "eventType": "issue", 41 | "eventNames": [ 42 | "issues", 43 | "project_card" 44 | ], 45 | "taskName": "Adds 'Needs: Triage' label for new issues", 46 | "actions": [ 47 | { 48 | "name": "addLabel", 49 | "parameters": { 50 | "label": "Needs Triage :mag:" 51 | } 52 | } 53 | ] 54 | } 55 | }, 56 | { 57 | "taskType": "trigger", 58 | "capabilityId": "IssueResponder", 59 | "subCapability": "IssueCommentResponder", 60 | "version": "1.0", 61 | "id": "NZKz_MGiV", 62 | "config": { 63 | "conditions": { 64 | "operator": "and", 65 | "operands": [ 66 | { 67 | "name": "isAction", 68 | "parameters": { 69 | "action": "created" 70 | } 71 | }, 72 | { 73 | "name": "isActivitySender", 74 | "parameters": { 75 | "user": { 76 | "type": "author" 77 | } 78 | } 79 | }, 80 | { 81 | "name": "hasLabel", 82 | "parameters": { 83 | "label": "Needs Author Feedback" 84 | } 85 | } 86 | ] 87 | }, 88 | "eventType": "issue", 89 | "eventNames": [ 90 | "issue_comment" 91 | ], 92 | "taskName": "Replace 'Needs: Author Feedback' with 'Needs: Attention' label when author comments", 93 | "actions": [ 94 | { 95 | "name": "addLabel", 96 | "parameters": { 97 | "label": "Needs Attention :wave:" 98 | } 99 | }, 100 | { 101 | "name": "removeLabel", 102 | "parameters": { 103 | "label": "Needs Author Feedback" 104 | } 105 | } 106 | ] 107 | } 108 | } 109 | ], 110 | "userGroups": [] 111 | } 112 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Welcome to the ARM Template What-If issues repo 2 | 3 | This repo is a little bit abnormal in that it is solely for keeping track of issues in the ARM Template what-if API. If you want to learn more about the what-if feature, you can take a look at this doc on the full capabilities of the what-if API and corresponding PowerShell cmdlet. 4 | 5 | * [ARM template deployment what-if operation (Preview)](https://docs.microsoft.com/en-us/azure/azure-resource-manager/template-deploy-what-if) 6 | * [What's new in ARM Templates - November 2019 #MSIgnite Session (YouTube)](https://www.youtube.com/watch?v=3D-JIKShrws&feature=youtu.be&t=771) 7 | 8 | For a guided tutorial on What-If, check out this [MS LEARN module](https://docs.microsoft.com/en-us/learn/modules/arm-template-test/). 9 | 10 | ## Recent Updates and Enhancements 11 | * We removed the need for the user/spn to have /write permission on the resources if the user specified the “no rbac” flag. Now we can add the flag ```-validationLevel "ProviderNoRbac"``` to achieve this. 12 | * To prevent secrets from leaking, ```SecureString``` and ```SecureObject``` parameters have always been replaced with placeholders in the WhatIf output. WhatIf will now also replace values dervied from ```SecureString``` and ```SecureObject``` parameters with placeholders. 13 | 14 | ## Ongoing Issues 15 | * **Issue:** WhatIf no longer checks for deny policy violations, leading to false negatives in validation. 16 | * **Status:** Fix awaiting rollout 17 | * **Issue:** WhatIf was previously only able to analyze nested deployment resources (Bicep modules) when all parameters passed to the nested deployment used “deploy-time constant” values, causing the evaluation of the template to “short-circuit” when a value derived from a reference to another resource was passed to a module as a parameter. This led to WhatIf analysis frequently being incomplete for templates relying on nested deployments. 18 | * **Status:** To help improve this significantly we made changes to whatIf that further expand the range of whatIf evaluation possible in a template, providing a more complete picture of before and after for all resources in the template. WhatIf is now able to provide the same experience regardless of how a deployment is broken up into modules or nested deployments. Note: This change may result in more latent “noise” (false positives) given that noise originating from resources in modules or nested deployments may have been surpressed due to short-ciruiting. We plan on addressing this in a future vNext project known as “Noise Reduction” mentioned below. 19 | 20 | ## Future Invemestments 21 | * **Deployment Stacks What-if:** You will be able to see WhatIf results evaluated in the context of deployment stacks, including aggregation of deletes and resource operations. ETA - 11/15/25 22 | * **Noise-reduction for Stacks What-if:** This works aims to improve WhatIf by now filtering out noisy properties, significantly reducing "what-if noise" and improving result reliability. ETA - 12/15/25 23 | 24 | ## Install PowerShell module 25 | To use What-If in PowerShell, install a preview version of the Az.Resources module from the PowerShell gallery by running: 26 | ``` 27 | Install-Module Az.Resources -RequiredVersion 1.12.1-preview -AllowPrerelease 28 | ``` 29 | If you previously installed an alpha version of the what-if module, take the steps described in the [ARM template deployment what-if operation (Preview)](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-deploy-what-if#uninstall-alpha-version) doc to uninstall that module. 30 | 31 | ## What types of issues are you looking for? 32 | 33 | The what-if issues fall into two buckets: 34 | 1. **Noise in the diff:** These are cases when what-if thinks a resource property will be changed (most often `deleted`) when in fact no change will occur. This is the *primary* motivation for this issue repo. 35 | 1. **Issues with formatting or general usability of the cmdlet or API:** There could be issues with formatting the diff, a parameter set may not be working correctly, etc. 36 | 37 | ## Why does noise occur? 38 | 39 | Often times, a property may be returned in a GET request for a resource that is not specified in the ARM template. The What-If API has a noise reduction service to catch these false positives and not return them. However, there are many cases where these could be missed. When this happens, it's likely that the what-if API will tell you that a resource will be modified and a specific property is deleted. 40 | 41 | Let's look at an example. 42 | 43 | Below is a storage account object declaration in an ARM Template, which is a little different than a pure REST API PUT body: 44 | ```json 45 | { 46 | "name": "storagedczol7xfovaoe", 47 | "type": "Microsoft.Storage/storageAccounts", 48 | "apiVersion": "2019-04-01", 49 | "sku": { 50 | "name": "Standard_LRS" 51 | }, 52 | "kind": "Storage", 53 | "location": "eastus", 54 | } 55 | ``` 56 | 57 | And here is only *part* of what the storage account looks like on GET. We've shortened in this readme, but you can see the full body [here](./storage-output.json): 58 | 59 | ```json 60 | { 61 | "sku": { 62 | "name": "Standard_LRS", 63 | "tier": "Standard" 64 | }, 65 | "kind": "Storage", 66 | "id": "/subscriptions/e93d3ee6-fac1-412f-92d6-bfb379e81af2/resourceGroups/test-005/providers/Microsoft.Storage/storageAccounts/storagedczol7xfovaoe", 67 | "name": "storagedczol7xfovaoe", 68 | "type": "Microsoft.Storage/storageAccounts", 69 | "location": "eastus", 70 | "tags": {}, 71 | "properties": { 72 | "networkAcls": { 73 | "bypass": "AzureServices", 74 | "virtualNetworkRules": [], 75 | "ipRules": [], 76 | "defaultAction": "Allow" 77 | }, 78 | "supportsHttpsTrafficOnly": true, 79 | ... 80 | } 81 | } 82 | ``` 83 | 84 | In order to output a clean diff, we do post-processing on the diff to remove all of this noise, but there are many cases that have not yet been accounted for. If we run the same storage account creation through what-if, then we will see some of this noise: 85 | 86 | ![Image of What-If output](./what-if-noise.PNG) 87 | 88 | ## How do I submit an issue? 89 | 90 | In order to take an action on noise you encounter, please open an issue and include the following information: 91 | 1. Resource type (i.e. `Microsoft.Storage/storageAccounts`) 92 | 1. apiVersion (i.e. `2019-04-01`) 93 | 1. Client (PowerShell, Azure CLI, API) 94 | 1. Relevant ARM Template code (we only need the resource object specified in `1` and `2`, but if it's easier you can include the entire template 95 | 1. Expected response (i.e. "I expected no noise since the template has not been modified since the resources were deployed) 96 | 1. Current (noisy) response (either include a screenshot of the what-if output, or copy/paste the text) 97 | 98 | ### Sample issue 99 | You can see a sample issue for the above [here](https://github.com/Azure/arm-template-whatif/issues/1). Hopefully it gets closed soon :) 100 | 101 | # Contributing 102 | 103 | This project welcomes contributions and suggestions. Most contributions require you to agree to a 104 | Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us 105 | the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. 106 | 107 | When you submit a pull request, a CLA bot will automatically determine whether you need to provide 108 | a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions 109 | provided by the bot. You will only need to do this once across all repos using our CLA. 110 | 111 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 112 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or 113 | contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 114 | 115 | 116 | --------------------------------------------------------------------------------