README.md

Initiative Definitions

Table of Contents

• Initiative (Policy Set) Definition Files
• Recommendations
• Example
• Reading List

Initiative (Policy Set) Definition Files

The names of the definition JSON files don't matter, the Initiative definitions are registered based on the name attribute. It is recommended that you use a GUID as the name. The solution also allows the use of JSON with comments by using .jsonc instead of .json for the file extension.

NOTE: When authoring policy/initiative definitions, check out the Maximum count of Azure Policy objects

The Initiative definition files are structured based on the official Azure Initiative definition structure published by Microsoft. There are numerous definition samples available on Microsoft's GitHub repository for azure-policy.

Optional: Policy definition groups allow custom initiatives to map to different regulatory compliance requirements. These will show up in the regulatory compliance blade in Azure Security Center as if they were built-in. In order to use this, the custom initiative must have both policy definition groups and group names defined. Policy definition groups must be pulled from a built-in initiative such as the Azure Security Benchmark initiative.Azure Initiative definition structure published by Microsoft. There are numerous definition samples available on Microsoft's GitHub Azure Security Benchmark Code.

Recommendations

• "name" should be a GUID - see https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7.2
• "category" should be one of the standard ones defined in built-in Policy definitions.
• Do *not- specify a fully qualified policyDefinitionName. The solution adds the scope during deployment. Warning: Specifying the scope will break the deployment.
• Do not specify an id
• Make the effects parameterized

Example

{
  "name": "Newly created GUID",
  "properties": {
    "displayName": "Your Initiative Display Name",
    "description": "Initiative Description",
    "metadata": {
      "version": "1.0.0",
      "category": "Category Name"
    },
    "policyDefinitionGroups": [
      {
        "name": "Azure_Security_Benchmark_v2.0_NS-1",
        "additionalMetadataId": "/providers/Microsoft.PolicyInsights/policyMetadata/Azure_Security_Benchmark_v2.0_NS-1"
      }
    ],
    "parameters": {
      "Parameter for policy one": {
        "type": "Array",
        "defaultValue": []
      },
      "Parameter for policy two": {
        "type": "string",
        "defaultValue": []
      }
    },
    "PolicyDefinitions": [
      {
        "policyDefinitionReferenceId": "Reference to policy number one",
        "policyDefinitionName": "Name of Policy Number One",
        "parameters": {
          "Parameter for policy one": {
            "value": "[parameters('Parameter for policy one')]"
          }
        }
      },
      {
        "policyDefinitionReferenceId": "Reference to policy number two",
        "policyDefinitionName": "Name of Policy Number Two",
        "parameters": {
          "Parameter for policy two": {
            "value": "[parameters('Parameter for policy two')]"
          }
        },
        "groupNames": [
            "Azure_Security_Benchmark_v2.0_NS-1"
        ]
      }
    ]
  }
}

Merging Built-In Initiatives

WARNING: Feature removed in 2.2

Reading List

1. Pipeline

2. Update Global Settings

3. Create Policy Definitions

4. Create Initiative Definitions

5. Define Policy Assignments

6. Define Policy Exemptions

7. Documenting Assignments and Initiatives

8. Operational Scripts

Return to the main page