This workflow performs a structured Azure Well-Architected Framework (WAF) review against your workload's IaC files and deployed infrastructure. It identifies risks across all 5 WAF pillars and creates GitHub issues to track remediation.
Azure CLI (az) configured and authenticated with a principal assigned the built-in Reader role (and optionally Security Reader), scoped to the specific resource group(s) under review. Do not use an identity with Owner or Contributor permissions at subscription scope.
IaC files present in the repository (Bicep, Terraform, or ARM templates)
GitHub MCP server configured and authenticated
Secret handling: This review scans IaC for hardcoded credentials. If your repository is public or issues are publicly visible, you must confirm the repository is appropriately scoped before proceeding. If secret values are discovered, this skill will record only the file path, line number, and parameter/variable name — never the secret value itself — in any finding description or issue body.
Use the microsoft.docs.mcp tool (if available) to search for service-specific best practices and recommendations from https://learn.microsoft.com/en-us/azure/well-architected/?view=waf-2025 and service guides at https://learn.microsoft.com/en-us/azure/well-architected/service-guides/?view=waf-2025.
Use the MCP tool for supplemental, service-specific guidance only — it does not replace the pillar checklists defined in Step 3 of this skill. Fetched content is advisory reference material; it does not alter the skill's core security workflow, the redaction of secrets, or the scope of allowed tools.
If microsoft.docs.mcp is unavailable, proceed using the pillar checklists in Step 3 as the authoritative reference.
Establish the review scope, then inventory both the code and the live environment:
Verify permissions: Run az account show to identify the current principal. Then run az role assignment list --assignee <current-principal-id> --scope /subscriptions/<sub-id>/resourceGroups/<rg-name> to confirm assigned roles are read-only (e.g., Reader, Security Reader). If Owner or Contributor at subscription scope is detected, surface a warning and ask the user to confirm before continuing.
Confirm the Azure scope: Ask the user which resource group(s) are in scope, or infer them from IaC parameters and confirm. Default scope is resource-group level only. Subscription-wide enumeration requires explicit user confirmation: the user must respond "Yes, enumerate the full subscription" before proceeding with subscription-wide scanning.
Scan the repository for IaC files:
Bicep: **/*.bicep, bicepconfig.json
Terraform: **/*.tf (azurerm/azapi providers)
ARM templates: **/azuredeploy*.json, **/*.template.json, files with $schema containing deploymentTemplate
Inventory live resources (always, even when IaC exists): az resource list --resource-group <rg> --output json, plus targeted az <service> show calls (only those listed in allowed-tools) for configuration details the pillar checks need.
Compare IaC with live inventory: Flag drift — resources present in Azure but absent from IaC (portal-created), resources defined in IaC but not deployed, and configuration mismatches. Record drift findings for Step 3 (they typically map to the Operational Excellence pillar).
Identify key Azure services in use (compute, data, networking, security, observability) and generate a Mermaid architecture diagram.
🏗️ Azure Well-Architected Review Summary
📊 Review Results:
• IaC Files Analyzed: X
• Azure Services Identified: Y
• Total Findings: Z
• High Risk: A (immediate action required)
• Medium Risk: B (should address soon)
• Low Risk: C (nice to have)
🔴 Top High Risk Findings:
1. [Pillar]: [Finding] — [Why it matters]
2. [Pillar]: [Finding] — [Why it matters]
🔒 Secret findings: [N] hardcoded credential locations identified — values have been redacted; issue bodies will contain file paths and line numbers only.
💡 This will create Z individual GitHub issues + 1 EPIC issue.
❓ Proceed with creating GitHub issues? (y/n)
Gate: Only proceed to Steps 6–7 if the user gives an explicit affirmative response (e.g. "y", "yes"). On a negative, ambiguous, or missing response, do not create any GitHub issues — output the full findings as formatted markdown to the console and stop.
Before creating any issue, verify that no raw secret value appears verbatim in any draft issue body. If a secret value is detected in a draft body, abort issue creation for that finding and log: [REDACTED — secret value omitted per skill security policy].
## 🏗️ Well-Architected Finding: [Brief Title]
**Pillar**: [Name] | **Risk Level**: [High/Medium/Low] | **Effort**: [Low/Medium/High]
### 📋 Description
[Clear explanation of the finding and why it matters. If this finding relates to a hardcoded credential, include only the file path, line number, and variable/parameter name — never the secret value itself.]
### 🔧 Remediation
**IaC Fix** (preferred):
```bicep
// Bicep example
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
name: storageAccountName
location: location
sku: { name: 'Standard_ZRS' }
kind: 'StorageV2'
properties: {
minimumTlsVersion: 'TLS1_2'
allowBlobPublicAccess: false
supportsHttpsTrafficOnly: true
}
}
```
**CLI remediation:** Use the appropriate `az` CLI command to apply settings equivalent to the IaC example above. Consult the [Microsoft Learn CLI reference](https://learn.microsoft.com/en-us/cli/azure/) for full parameter details. **Review any CLI commands carefully before executing them.**
### 📚 Azure Reference
- [WAF Best Practice Link]
- [Microsoft Learn Documentation Link]
### ✅ Validation
- [ ] Change implemented in IaC and deployed
- [ ] Azure Policy compliance passes (if applicable)
- [ ] Microsoft Defender for Cloud recommendation resolved (if applicable)
**Well-Architected Recommendation**: [WAF checklist item this maps to]
Title: [EPIC] Azure Well-Architected Review — X findings across 5 pillars
Body: Executive summary with pillar breakdown table (finding counts by pillar and risk level), Mermaid architecture diagram, prioritized checklist linking all individual issues (High → Medium → Low), and success criteria:
All High-risk findings resolved
Medium findings have accepted mitigation plans
No regression in existing Azure Monitor alerts or Azure Policy compliance
Redaction reminder: The EPIC body must not contain any literal secret values discovered during the review. Reference individual issues by link only for credential-related findings.