Added binding reference Azure#2995 (Azure#2996)

BernieWhite · web-flow · commit df2d5ef1afba · 2024-07-20T17:53:53.000+10:00
* Added binding reference Azure#2995 * Updated baseline metadata * Change log updates
diff --git a/docs/CHANGELOG-v1.md b/docs/CHANGELOG-v1.md
diff --git a/docs/concepts/policy-as-rules.md b/docs/concepts/policy-as-rules.md
@@ -86,6 +86,29 @@ For example:
 Export-AzPolicyAssignmentRuleData -AssignmentFile '.\<subscriptionId>.assignment.json'
 ```
 
+## Running policy rules
+
+Rules and an initial baseline are generated in a file ending in `.Rule.jsonc`.
+This file extension and format are automatically detected by PSRule when it is run from an included source path.
+To start using the policy rules, copy the file to the default include sub-directory (`.ps-rule/`) in the root of your repository.
+
+Additionally, the following setup is required to scan Infrastructure as Code (IaC):
+
+1. Set a binding configuration.
+2. Configure expansion for processing Bicep or ARM templates.
+3. Include the `PSRule.Rules.Azure` module.
+4. Optionally specify a baseline to limit the rules evaluated to policy rules.
+
+### Generated baseline
+
+<!-- module:version v1.33.0 -->
+
+When exporting policies, PSRule for Azure will automatically generate a baseline including any generated rules.
+By default, this baseline is called `Azure.PolicyBaseline.All`.
+If you change the prefix of generated rules the baseline will be named `<Prefix>.PolicyBaseline.All`.
+
+See [Using baselines](../working-with-baselines.md#using-baselines) for examples on how to use a baseline in a run.
+
 ## Customizing the generated rules
 
 PSRule for Azure allows you to:
@@ -108,16 +131,6 @@ configuration:
   - /providers/Microsoft.Authorization/policyDefinitions/b54ed75b-3e1a-44ac-a333-05ba39b99ff0
 ```
 
-## Generated baseline
-
-<!-- module:version v1.33.0 -->
-
-When exporting policies, PSRule for Azure will automatically generate a baseline including any generated rules.
-By default, this baseline is called `Azure.PolicyBaseline.All`.
-If you change the prefix of generated rules the baseline will be named `<Prefix>.PolicyBaseline.All`.
-
-See [Using baselines](../working-with-baselines.md#using-baselines) for examples on how to use a baseline in a run.
-
 ## Duplicate policies
 
 <!-- module:version v1.33.0 -->
@@ -143,3 +156,9 @@ This allows you to:
 - Reduce noise reporting the same issue multiple times.
 
 To override this behavior use the `-KeepDuplicates` parameter switch when running `Export-AzPolicyAssignmentRuleData`.
+
+## Recommended content
+
+- [Using custom rules](../customization/using-custom-rules.md)
+- [Creating your pipeline](../creating-your-pipeline.md)
+- [Working with baselines](../working-with-baselines.md)
diff --git a/docs/customization/enforce-codeowners.md b/docs/customization/enforce-codeowners.md
@@ -60,9 +60,9 @@ Some key points to call out with the rule snippet include:
   PSRule for Azure exposes a `Template` and `Parameter` source for resources originating from a template.
 
 !!! Tip
-    For recommendations on naming and storing rules see [storing custom rules][3].
+    For recommendations on naming and storing rules see [using custom rules][3].
 
-  [3]: storing-custom-rules.md
+  [3]: using-custom-rules.md
 
 ## Binding type
 
@@ -78,8 +78,8 @@ To configure type binding:
 # Configure binding options
 binding:
   targetType:
-  - 'resourceType'
-  - 'type'
+    - 'resourceType'
+    - 'type'
 ```
 
 Some key points to call out include:
diff --git a/docs/customization/enforce-custom-tags.md b/docs/customization/enforce-custom-tags.md
@@ -43,9 +43,9 @@ Some key points to call out with the rule snippet include:
 - The automatic variable `$TargetObject` automatically exposes the current resource being processed.
 
 !!! Tip
-    For recommendations on naming and storing rules see [storing custom rules][1].
+    For recommendations on naming and storing rules see [using custom rules][1].
 
-  [1]: storing-custom-rules.md
+  [1]: using-custom-rules.md
 
 ## Adding mandatory tags
 
@@ -147,12 +147,12 @@ To configure type binding:
 - Create/ update the `ps-rule.yaml` file within the root of the repository.
 - Add the following configuration snippet.
 
-```yaml
+```yaml title="ps-rule.yaml"
 # Configure binding options
 binding:
   targetType:
-  - 'resourceType'
-  - 'type'
+    - 'resourceType'
+    - 'type'
 ```
 
 Some key points to call out include:
diff --git a/docs/customization/storing-custom-rules.md b/docs/customization/storing-custom-rules.md
diff --git a/docs/customization/using-custom-rules.md b/docs/customization/using-custom-rules.md
@@ -0,0 +1,131 @@
+---
+description: This topic covers how you can use custom rules to test Azure Infrastructure as Code.
+author: BernieWhite
+---
+
+# Using custom rules
+
+PSRule for Azure covers common use cases that align to the [Microsoft Azure Well-Architected Framework (WAF)][1].
+In addition to WAF alignment you may have a requirement to enforce organization specific rules.
+
+For example:
+
+- Required tags on a resource group.
+- Code ownership for sensitive resource types.
+- Apply similar controls to Infrastructure as Code that are deployed via Azure Policies.
+
+PSRule allows custom rules to be layered on.
+These custom rules work side-by-side with PSRule for Azure.
+
+  [1]: https://learn.microsoft.com/azure/well-architected/
+
+!!! Abstract
+    This topic covers how you can use custom rules to test Azure Infrastructure as Code (IaC).
+
+## Requirements
+
+For custom rules to work with IaC the following requirements must be configured:
+
+1. Set a binding configuration.
+2. Configure expansion for processing Bicep or ARM templates.
+3. Include the `PSRule.Rules.Azure` module.
+
+### Set binding configuration
+
+Rules packaged within PSRule for Azure will automatically detect Azure resources by their type properties.
+Standalone rules will get their type binding configuration from `ps-rule.yaml` instead.
+When binding is not configured, custom rules will typically be ignored.
+
+To configure type binding:
+
+- Create/ update the `ps-rule.yaml` file within the root of the repository.
+- Add the following configuration snippet.
+
+```yaml title="ps-rule.yaml"
+# Configure binding options
+binding:
+  targetType:
+    - 'resourceType'
+    - 'type'
+```
+
+### Configuring expansion
+
+PSRule for Azure performs [expansion][2] on Bicep and ARM template files it finds in your repository.
+Enabling expansion is required for testing any IaC in your repository.
+The requirements for custom rules are no different then using the built-in rules included within PSRule for Azure.
+
+To configure expansion see either:
+
+- [Using Bicep source](../using-bicep.md)
+- [Using templates](../using-templates.md)
+
+  [2]: ../faq.md#what-is-expansion
+
+### Including PSRule for Azure
+
+When creating custom rules to test Azure IaC including PSRule for Azure is required for most scenarios.
+PSRule for Azure performs [expansion][2] on Bicep and ARM template files it finds in your repository.
+
+You can include PSRule for Azure by specifying `PSRule.Rules.Azure` in one of the following:
+
+- **Pipeline** &mdash; The `modules:` parameter in [GitHub Actions or Azure Pipelines][3].
+- **PowerShell** &mdash; The `-Module` parameter with the [PowerShell cmdlets][4].
+- **Options** &mdash; - The `Include.Module` [option][5].
+
+  [3]: ../creating-your-pipeline.md
+  [4]: ../creating-your-pipeline.md
+  [5]: https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Options/#includemodule
+
+## Using a standard file path
+
+Rules can be standalone or packaged within a module.
+Standalone rules are ideal for a single project such as an Infrastructure as Code (IaC) repository.
+To reuse rules across multiple projects consider packaging these as a module.
+
+The instructions for packaging rules in a module can be found here:
+
+- [Packaging rules in a module][6]
+
+To store standalone rules we recommend that you:
+
+- **Use .ps-rule/** &mdash; Create a sub-directory called `.ps-rule` in the root of your repository.
+  Use all lower-case in the sub-directory name.
+  Put any custom rules within this sub-directory.
+- **Use files ending with .Rule.ps1 | .Rule.yaml | .Rule.jsonc** &mdash;
+  PSRule uses a file naming convention to discover rules.
+  We recommend using a file name that ends in `.Rule.ps1` or `.Rule.yaml` or `.Rule.jsonc`.
+
+!!! note
+    Build pipelines are often case-sensitive or run on Linux-based systems.
+    Using the casing rule above reduces confusion latter when you configure continuous integration (CI).
+
+  [6]: https://microsoft.github.io/PSRule/stable/authoring/packaging-rules/
+
+## Naming rules
+
+When running PSRule, rule names must be unique.
+PSRule for Azure uses the name prefix of `Azure.` on all rules and resources included in the module.
+
+!!! example
+    The following names are examples of rules included within PSRule for Azure:
+
+    - `Azure.AKS.Version`
+    - `Azure.AKS.AuthorizedIPs`
+    - `Azure.SQL.MinTLS`
+
+When naming custom rules we recommend that you:
+
+- **Use a standard prefix** &mdash; You can use the `Local.` or `Org.` prefix for standalone rules.
+  - Alternatively choose a short prefix that identifies your organization.
+- **Use dotted notation** &mdash; Use dots to separate rule name.
+- **Use a maximum length of 35 characters** &mdash; The default view of `Invoke-PSRule` truncates longer names.
+  PSRule supports longer rule names however if `Invoke-PSRule` is called directly consider using `Format-List`.
+
+## Related content
+
+- [Using Bicep source](using-bicep.md)
+- [Using templates](using-templates.md)
+- [Creating your pipeline](creating-your-pipeline.md)
+
+*[IaC]: Azure Resource Manager
diff --git a/docs/expanding-source-files.md b/docs/expanding-source-files.md
@@ -179,6 +179,12 @@ properties:
 
 To override, configure [`AZURE_MANAGEMENT_GROUP`](setup/configuring-expansion.md#deployment-management-group).
 
+## Related content
+
+- [Using Bicep source](using-bicep.md)
+- [Using templates](using-templates.md)
+- [Creating your pipeline](creating-your-pipeline.md)
+
 *[WAF]: Well-Architected Framework
 *[ARM]: Azure Resource Manager
 *[PR]: Pull Request
diff --git a/docs/faq.md b/docs/faq.md
@@ -26,9 +26,12 @@ For general FAQ see [PSRule - Frequently Asked Questions (FAQ)][ps-rule-faq], in
 ## What is a rule?
 
 A rule is a named set of checks and documentation.
+Each rule is tests a specific aspect of an Azure resource or deployment to determine if
+it is aligned with the [Microsoft Azure Well-Architected Framework][AWAF].
 You can find the documentation for each rule under [reference][1].
 
   [1]: en/rules/module.md
+  [AWAF]: https://learn.microsoft.com/azure/architecture/framework/
 
 ## What is a baseline?
 
@@ -40,9 +43,22 @@ Continue reading [working with baselines][2] for a detailed breakdown.
 
   [2]: working-with-baselines.md
 
+## What is expansion?
+
+Expansion is a feature of PSRule for Azure that converts Azure Infrastructure as Code (IaC) to a testable Azure resource.
+IaC format such as Bicep and ARM templates, support dynamic capabilities such parameters, variables, and conditions...
+These dynamic capabilities allow customers to create modular reusable code that can scale across an organization.
+However, to determine if a specific Azure resource meets the requirements of an organization the final state must be known.
+
+Expansion resolves these dynamic capabilities so that a final state for each resource can be tested by rules.
+Noting the final expanded state provided by PSRule for Azure is a close approximation.
+This close approximation allows testing of Azure resources offline directly from code before deployment to Azure.
+
+Continue reading [Expanding source files](expanding-source-files.md).
+
 ## Is Terraform supported?
 
-Currently PSRule for Azure supports testing Azure resources from Infrastructure as Code (IaC) with:
+Currently PSRule for Azure supports testing Azure resources from IaC with:
 
 - Azure Resource Manager (ARM) templates.
 - Azure Bicep deployments.
@@ -89,8 +105,6 @@ You may want to use PSRule to enforce tagging or something similar early in a De
 
 We have a walk through scenario [Enforcing custom tags][9] to get you started.
 
-  [AWAF]: https://learn.microsoft.com/azure/architecture/framework/
-
 ## How do I create a custom rule to enforce code ownership?
 
 GitHub, Azure DevOps, and other DevOps platforms may implement code ownership.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -140,7 +140,7 @@ There is a few common causes of this issue including:
     You may be able to use `git mv` to change the case of a file if it is committed to the repository incorrectly.
 
   [5]: https://aka.ms/ps-rule/naming
-  [6]: customization/enforce-custom-tags.md#binding-type
+  [6]: customization/using-custom-rules.md#set-binding-configuration
   [12]: working-with-baselines.md#quarterly-baseline
   [13]: https://aka.ms/ps-rule/options#ruleincludelocal
   [14]: working-with-baselines.md#including-custom-rules
diff --git a/docs/working-with-baselines.md b/docs/working-with-baselines.md
@@ -8,7 +8,7 @@ A baseline is a standard PSRule artifact that combines rules and configuration.
 PSRule for Azure provides several baselines that can be referenced when running PSRule.
 
 !!! Abstract
-    This topic covers how to use the baselines shipped with PSRule for Azure.
+    This topic covers how to use standard baselines shipped with PSRule for Azure or custom baselines you define.
 
 ## Quarterly baselines
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -67,7 +67,7 @@ nav:
       - Suppression: concepts/suppression.md
       - Policy as rules: concepts/policy-as-rules.md
     - Customization:
-      - Storing custom rules: customization/storing-custom-rules.md
+      - Using custom rules: customization/using-custom-rules.md
       - Enforcing custom tags: customization/enforce-custom-tags.md
       - Enforcing code ownership: customization/enforce-codeowners.md
       - Permit outbound management: customization/permit-outbound-management.md
@@ -148,7 +148,8 @@ plugins:
       install-instructions.md: install.md
       validating-locally.md: install.md
       using-metadata.md: using-templates.md
-      customization/index.md: customization/storing-custom-rules.md
+      customization/index.md: customization/using-custom-rules.md
+      customization/storing-custom-rules.md: customization/using-custom-rules.md
       en/asb-v3.md: en/mcsb-v1.md
       setup/configuring-options.md: setup/index.md
 
diff --git a/src/PSRule.Rules.Azure/rules/Baseline.Rule.yaml b/src/PSRule.Rules.Azure/rules/Baseline.Rule.yaml
diff --git a/src/PSRule.Rules.Azure/rules/MCSB.Rule.yaml b/src/PSRule.Rules.Azure/rules/MCSB.Rule.yaml
