---
name: azv-bicep-policy-check
description: Check a Bicep template against the Azure Policy assignments in the target Azure environment to determine whether the resources would be compliant before deployment. Uses the checkPolicyRestrictions REST API for fast server-side evaluation, with a legacy CLI fallback. Produces a per-resource compliance report with remediation guidance.
license: MIT
metadata:
  author: AzVerify
  version: "1.0"
  project: AzVerify
---

Check Bicep templates against the Azure Policy assignments active in the target environment. Reports whether each resource would be compliant, non-compliant, or requires manual evaluation — before any deployment occurs.

**Input**: A solution folder containing Bicep templates (`main.bicep`) and a `.bicepparam` file, plus an Azure target scope (resource group name, subscription ID). The user can specify these, or the skill will auto-discover and prompt for missing inputs.

**Tools required**: File system tools (read files), Terminal (for running `az` CLI commands)

**Reference files**:
- `.github/skills/shared/azure-resource-model.md` — Shared resource metadata model definition
- `.github/skills/shared/azure-resource-configs.md` — Per-resource-type configuration schemas and auto-detection rules
- `.github/skills/shared/data/azure-property-paths.json` — Azure Property Retrieval Mapping (MCP tools, CLI fallbacks, ARM JSON paths)

**Shared procedures** (MUST follow):
- `.github/skills/shared/procedures/azure-authentication.md` — Azure session check procedure
- `.github/skills/shared/procedures/bicep-parsing.md` — Bicep template parsing procedure

---

## Steps

### 1. Check Azure Authentication

Follow the procedure in `.github/skills/shared/procedures/azure-authentication.md`. **HARD GATE** — stop if not authenticated.

### 2. Accept Inputs

Identify the solution folder, the Bicep template, the parameter file, and the target scope.

#### 2a. Identify the Solution Folder

**If the user specifies a folder path:**
- Verify the folder exists
- Use it as the solution folder

**If no folder is specified:**
- Search the workspace for folders containing a `main.bicep` file
- If exactly one is found, use it (announce which folder)
- If multiple are found, present the list and ask the user to select one
- If none are found, ask the user to provide a solution folder

#### 2b. Identify the Bicep Template

- Verify `main.bicep` exists in the solution folder
- If not found, report an error:
```
## No Bicep Template Found

No `main.bicep` file found in `<folder-path>`.
This skill requires a Bicep template to check policy compliance.
```
- Stop execution

#### 2c. Identify the Parameter File

**If exactly one `.bicepparam` file exists in the solution folder:**
- Use it as the parameter file (announce which file)

**If multiple `.bicepparam` files exist:**
- Present the list and ask the user to select one

**If no `.bicepparam` file exists:**
- Warn the user:
```
⚠️ No `.bicepparam` file found in `<folder-path>`. Default parameter values will be used when evaluating policy compliance.
```
- Proceed without a parameter file

#### 2d. Identify the Target Scope

**If the user specifies a resource group name:**
- Use it as the target scope
- Verify the resource group exists: run `az group show --name <name>` and capture the subscription ID from the result

**If the user specifies a subscription ID:**
- Use it as the target scope for subscription-level policy retrieval

**If no scope is specified, try to infer it:**
1. From the `.bicepparam` file: look for comments or `using` declarations indicating a target resource group
2. If a resource group name is found, propose it:
```
The `.bicepparam` file references resource group `<name>`. Use this as the target scope? (yes/no)
```
3. If no scope can be inferred, ask the user:
```
Which Azure resource group are you targeting for this deployment?
```
- Wait for user input

### 3. Parse Templates into Expected Resource Model

Read the Bicep template and parameter file to build an **expected resource model** — what the templates declare should exist.

#### 3a. Read and parse the `.bicepparam` file

Read the `.bicepparam` file and extract all parameter values. For each `param <name> = <value>` line, record the name and resolved value.

#### 3b. Read and parse `main.bicep` and all module files

Read `main.bicep` and every Bicep module it references in `modules/`. For each `resource` block, extract:

- **Resource type** (e.g., `Microsoft.Web/sites`)
- **API version**
- **Symbolic name** (Bicep variable name)
- **`name` property** — resolve parameter references using the values from Step 3a where possible
- **All other properties** — collect the full set of declared properties for policy evaluation (location, SKU, kind, properties.* fields)

Store this as the **expected resource model**: a list of resources, each with their type, name, and full declared properties.

If a property value references a parameter that cannot be resolved (e.g., it depends on deployment-time input), record it as `<unresolved: paramName>`.

#### 3c. Build resource group resource entry

Many policies (e.g., required tags) target the **resource group itself** (`Microsoft.Resources/subscriptions/resourceGroups`), not the resources inside it. The skill must check the resource group as a separate resource.

**If the resource group already exists:**
- Run `az group show --name <rgName> -o json` to get its current tags and location
- Build a resource entry using the existing RG properties

**If the resource group does not exist yet (new deployment):**
- Build a resource entry using:
  - `name` — the target resource group name
  - `location` — the `location` parameter from the `.bicepparam` file
  - `tags` — look for a `resourceGroupTags` or similar parameter in the `.bicepparam` file. If none exists, use `{}`

Add this as the **first entry** in the expected resource model:

```
Resource: <rgName>
Type: Microsoft.Resources/subscriptions/resourceGroups
API version: 2024-03-01
Properties: { location, tags }
```

> This adds only **one extra API call** (~1–3 seconds) to the check, keeping total execution fast.

### 4. Evaluate Policy Compliance via checkPolicyRestrictions API

Use the Azure `checkPolicyRestrictions` REST API to evaluate each resource against **all** active policies in a single call per resource. This replaces sequential CLI fetches of initiatives and definitions.

> **Performance goal**: 1 REST call per resource (typically 2–5 calls total). No initiative expansion, no definition fetching, no local rule evaluation needed — Azure does all policy evaluation server-side.

#### 4a. Build resource content payloads

For each resource in the expected resource model (Step 3), **including the resource group from Step 3c**, build a `resourceContent` JSON object matching what would be deployed. Include:

**For the resource group entry (from Step 3c):**
- `type` — `Microsoft.Resources/subscriptions/resourceGroups`
- `location` — resolved from parameters
- `name` — the target resource group name
- `tags` — resolved from parameters, or `{}` if none specified

> The resource group check uses **subscription-level scope** (even if the RG exists), since RG creation happens at subscription level. Use: `/subscriptions/$subscriptionId/providers/Microsoft.PolicyInsights/checkPolicyRestrictions?api-version=2022-03-01`

**For all other resources:**
- `type` — the full resource type (e.g., `Microsoft.DevCenter/devcenters`)
- `location` — resolved from parameters
- `name` — resolved from parameters
- `tags` — resolved from parameters (use `{}` if empty/unresolved)
- `sku` — if applicable
- `kind` — if applicable
- `properties` — the full properties bag, resolved from parameters where possible

For properties that reference unresolved parameters, use a reasonable placeholder value and flag the resource for manual review on those properties.

#### 4b. Run ALL resources in a single terminal invocation

> **CRITICAL**: All resource checks MUST be executed in a **single terminal command**. Do NOT run separate terminal commands per resource.

Build a single PowerShell script that:
1. Defines all resource payloads as an array (resource group FIRST, with `isRG = $true`)
2. Determines scope URLs: subscription-level for the RG itself, RG-level for child resources (subscription-level fallback if RG doesn't exist)
3. Loops through each resource, calling `az rest --method POST` against the `checkPolicyRestrictions` endpoint
4. Outputs all results as JSON

API endpoint pattern: `/subscriptions/$subscriptionId[/resourceGroups/$rgName]/providers/Microsoft.PolicyInsights/checkPolicyRestrictions?api-version=2022-03-01`

Each resource payload: `@{ resourceDetails = @{ resourceContent = <content>; apiVersion = <version> } }`

> **Performance**: Completes in **one terminal invocation** taking ~5–15 seconds total (1–3 seconds per API call).

#### 4c. Handle API errors gracefully

- **403 Forbidden**: The user may lack `Microsoft.PolicyInsights/checkPolicyRestrictions/read` permission. Fall back to the **legacy approach** (Step 4-fallback below).
- **404 Not Found**: The resource group doesn't exist yet. Retry with subscription-level scope.
- **Other errors**: Report the error and fall back to the legacy approach.

#### 4d. Parse API response

The `checkPolicyRestrictions` response contains two key sections:
- **`fieldRestrictions[]`** — per-field value restrictions with `field`, `restrictions[].result`, `restrictions[].values`, policy IDs, and `policyEffect`
- **`contentEvaluationResult.policyEvaluations[]`** — full evaluation results with `evaluationResult` ("NonCompliant"/"Compliant"), `effectDetails.effect`, and policy display names

---

### 4-fallback. Legacy Approach (if checkPolicyRestrictions is unavailable)

If the `checkPolicyRestrictions` API is not available (403, unsupported region, or older API version), fall back to this approach:

1. Fetch all assignments in one call: `az policy assignment list --scope "/subscriptions/$subscriptionId" -o json`
2. For each initiative, expand definitions and keyword-filter by resource type
3. Fetch individual definitions only for the matched subset
4. Evaluate policy rules locally against resource properties

This fallback is slower (2–5+ minutes for environments with many assignments) but does not require the `Microsoft.PolicyInsights` RP.

---

### 5. Determine Compliance Status per Resource

Map the `checkPolicyRestrictions` API response to compliance status for each resource.

#### 5a. Classify from contentEvaluationResult

For each entry in `contentEvaluationResult.policyEvaluations`:

- **`evaluationResult: "NonCompliant"` + `effect: "deny"`** → Resource would be **Non-Compliant** (deployment blocked)
- **`evaluationResult: "NonCompliant"` + `effect: "audit"`** → Resource would be **Non-Compliant** (deployment allowed but flagged)
- **`evaluationResult: "NonCompliant"` + `effect: "auditIfNotExists"`** → **Needs manual review** (depends on related resource existence in Azure)
- **`evaluationResult: "NonCompliant"` + `effect: "modify"`** → **Modify policy active** — Azure will auto-remediate post-deployment, but the value CAN be set proactively in the Bicep template. Report what the modify policy will change.
- **`evaluationResult: "NonCompliant"` + `effect: "deployIfNotExists"`** → **Auto-remediated** after deployment (separate resource created by policy; cannot be pre-set in Bicep)

If `policyEvaluations` is empty or all results are compliant, the resource is **Compliant**.

#### 5b. Classify from fieldRestrictions

For each entry in `fieldRestrictions`:
- If the resource's declared value for the restricted field is in the allowed `values` list → **Compliant** for this restriction
- If the resource's declared value is NOT in the allowed list and the effect is `deny` → **Non-Compliant** (deployment blocked)
- If the resource's declared value is NOT in the allowed list and the effect is `audit` → **Non-Compliant** (flagged)
- If the field value is unresolved (`<unresolved: paramName>`) → **Needs manual review**

#### 5c. Aggregate per resource

Combine `contentEvaluationResult` and `fieldRestrictions` classifications. The worst status wins:
1. **Non-Compliant (deny)** — highest severity
2. **Non-Compliant (audit)**
3. **Needs manual review**
4. **Modify policy active** — auto-remediated but can be proactively fixed in Bicep
5. **Auto-remediated (deployIfNotExists)** — separate resource created by policy; informational only
6. **Compliant** — lowest severity

---

### 6. Build Compliance Report

Aggregate the per-resource, per-policy evaluations into a summary compliance report.

#### 6a. Overall summary

Present a top-level summary table:

```
## Policy Compliance Check — <folder-name>

| # | Resource | Type | Status |
|---|----------|------|--------|
| 1 | <rgName> | Resource Group | ❌ Non-Compliant (deny) |
| 2 | <name> | <type> | ✅ Compliant |
| 3 | <name> | <type> | ⚠️ Non-Compliant (audit) |
| 4 | <name> | <type> | 🔧 Modify policy active |
| 5 | <name> | <type> | 🔄 Auto-remediated (DINE) |
| 6 | <name> | <type> | ❓ Needs manual review |

**Scope**: <resourceGroupName> (Subscription: <subscriptionName>)
**Policies evaluated**: <count> policy assignments (<count> definitions)
**Result**: <X> compliant, <Y> non-compliant (deny), <Z> non-compliant (audit), <M> modify policies active, <W> need review
```

> **Note**: The resource group itself is always checked as the first resource. Policies that target `Microsoft.Resources/subscriptions/resourceGroups` (e.g., required tags on resource groups) are evaluated here. This catches tag requirements, naming conventions, and other RG-level policies that would otherwise be missed.

#### 6b. Non-compliant resource details

For each non-compliant resource, show: Policy name, Assignment, Effect, Reason, Expected vs Actual values, and Remediation guidance.

#### 6c. Needs-manual-review resource details

Show: Policy name, Reason (unresolvable property or condition involving related resources), and recommend `az policy state list --resource <resourceId>` after deployment.

#### 6d. Modify policy details (actionable)

Show: Policy name, Assignment, Effect (modify), what it does, fields modified (table: Field, Policy action, Value source), current Bicep value, and proactive fix suggestion (set tags/properties in `.bicepparam` file).

#### 6e. Auto-remediated resource notes (deployIfNotExists)

Show: Policy name, Effect (deployIfNotExists), note that no Bicep changes are required — the remediation creates a separate resource post-deployment.

---

### 7. Offer Next Steps

Offer the user:
- **`fix`** — Update Bicep templates to resolve non-compliant settings AND proactively set modify-policy values
- **`save report`** — Save compliance report as `policy-compliance-report.md` in the solution folder
- **Deploy anyway** / **Re-check** / **Preview with azv-bicep-whatif**

#### 7a. Fix non-compliant and modify-policy Bicep templates (if requested)

**For deny/audit non-compliant resources** with deterministic fixes:
- Locate the property in the Bicep module, update the value, report the change

**For modify policies (proactive fix)**:
- For tag policies: add required tag keys to `.bicepparam` with placeholder values
- For other properties: set to the value the policy would apply, if deterministic
- For runtime-dependent values: add placeholder with comment explaining expected source

**For resource group-level policies** (e.g., RequireTag deny):
- Report that RG creation must include required tags
- If `targetScope = 'subscription'`, add tags to the RG resource in Bicep

- For non-compliant resources where the required change is not deterministic (e.g., involves unresolved parameters or complex conditions):
  - Report that the change must be made manually and provide guidance
- After all updates, present the list of changes made and suggest running **azv-bicep-policy-check** again to confirm

#### 7b. Save report (if requested)

If the user replies `save report` (or equivalent):

- Write the full compliance report as `policy-compliance-report.md` in the solution folder
- Confirm:
  ```
  Saved compliance report to `<folder>/policy-compliance-report.md`.
  ```

---

### 8. Important Notes

- Uses `checkPolicyRestrictions` REST API (2022-03-01) for server-side evaluation (5–15 seconds for 3–5 resources). Falls back to legacy assignment-expansion approach (2–5+ min) if API returns 403.
- Requires `Microsoft.PolicyInsights/checkPolicyRestrictions/read` permission. Most Reader/Contributor roles include this.
- Policies requiring live Azure state (e.g., `auditIfNotExists`) are marked `Needs manual review`. Same for unresolvable deployment-time parameters.
- The resource group is always checked as a separate resource to catch RG-level policies (e.g., required tags). New RGs use subscription-level scope.
- Effect precedence: `deny` (blocks deployment) > `audit` (flags) > `modify` (auto-remediates, actionable in Bicep) > `deployIfNotExists` (informational).
- The API automatically evaluates inherited policies (management group → subscription → resource group) and handles API version matching.
- This skill operates independently — does not require a diagram or prior `azv-diagram-to-bicep` run.