Skip to content

Commit 27a554a

Browse files
v-regandownerv-regandowner
authored
Merge pull request #212345 from timwarner-msft/timwarner-attarticle
Add new policy attestation article
2 parents ee7d14d + 012b1a0 commit 27a554a

File tree

3 files changed

+85
-46
lines changed

3 files changed

+85
-46
lines changed

‎articles/governance/policy/concepts/attestation-structure.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Details of the Azure Policy attestation structure
3+
description: Describes the components of the Azure Policy attestation JSON object.
4+
ms.date: 09/23/2022
5+
ms.topic: conceptual
6+
ms.author: timwarner
7+
author: timwarner-msft
8+
---
9+
# Azure Policy attestation structure
10+
11+
`Microsoft.PolicyInsights/attestations`, called an Attestation resource, is a new proxy resource type
12+
that sets the compliance states for targeted resources in a manual policy. You can only have one
13+
attestation on one resource for an individual policy. In preview, Attestations are available
14+
only through the Azure Resource Manager (ARM) API.
15+
16+
Below is an example of creating a new attestation resource:
17+
18+
```http
19+
PUT http://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/attestations/{name}?api-version=2019-10-01
20+
```
21+
22+
## Request body
23+
24+
Below is a sample attestation resource JSON object:
25+
26+
```json
27+
"properties": {
28+
"policyAssignmentId": "/subscriptions/{subscriptionID}/providers/microsoft.authorization/policyassignments/{assignmentID}",
29+
"policyDefinitionReferenceId": "{definitionReferenceID}",
30+
"complianceState": "Compliant",
31+
"expiresOn": "2023-07-14T00:00:00Z",
32+
"owner": "{AADObjectID}",
33+
"comments": "This subscription has passed a security audit. See attached details for evidence",
34+
"evidence": [
35+
{
36+
"description": "The results of the security audit.",
37+
"sourceUri": "https://gist.github.com/contoso/9573e238762c60166c090ae16b814011"
38+
},
39+
{
40+
"description": "Description of the attached evidence document.",
41+
"sourceUri": "https://storagesamples.blob.core.windows.net/sample-container/contingency_evidence_adendum.docx"
42+
},
43+
],
44+
}
45+
```
46+
47+
|Property |Description |
48+
|---------|---------|
49+
|policyAssignmentId |Required assignment ID for which the state is being set. |
50+
|policyDefinitionReferenceId |Optional definition reference ID, if within a policy initiative. |
51+
|complianceState |Desired state of the resources. Allowed values are `Compliant`, `NonCompliant`, and `Unknown`. |
52+
|owner |Optional Azure AD object ID of responsible party. |
53+
|comments |Optional description of why state is being set. |
54+
|evidence |Optional link array for attestation evidence. |
55+
56+
Because attestations are a separate resource from policy assignments, they have their own lifecycle. You can PUT, GET and DELETE attestations by using the ARM API. See the [Policy REST API Reference](/rest/api/policy) for more details.
57+
58+
## Next steps
59+
60+
- Review [Understanding policy effects](effects.md).
61+
- Study the [initiative definition structure](./initiative-definition-structure.md)
62+
- Review examples at [Azure Policy samples](../samples/index.md).

‎articles/governance/policy/concepts/effects.md

Lines changed: 20 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Understand how effects work
33
description: Azure Policy definitions have various effects that determine how compliance is managed and reported.
44
author: timwarner-msft
5-
ms.date: 09/21/2022
5+
ms.date: 09/23/2022
66
ms.topic: conceptual
77
ms.author: timwarner
88
---
@@ -756,6 +756,23 @@ you'll need to create an attestation for that compliance state.
756756
> During Public Preview, support for manual policy is available through various Microsoft Defender
757757
> for Cloud regulatory compliance initiatives. If you are a Microsoft Defender for Cloud [Premium tier](https://azure.microsoft.com/pricing/details/defender-for-cloud/) customer, refer to their experience overview.
758758
759+
Currently, the following regulatory policy initiatives include policy definitions containing the manual effect:
760+
761+
- FedRAMP High
762+
- FedRAMP Medium
763+
- HIPAA
764+
- HITRUST
765+
- ISO 27001
766+
- Microsoft CIS 1.3.0
767+
- Microsoft CIS 1.4.0
768+
- NIST SP 800-171 Rev. 2
769+
- NIST SP 800-53 Rev. 4
770+
- NIST SP 800-53 Rev. 5
771+
- PCI DSS 3.2.1
772+
- PCI DSS 4.0
773+
- SOC TSP
774+
- SWIFT CSP CSCF v2022
775+
759776
The following example targets Azure subscriptions and sets the initial compliance state to `Unknown`.
760777

761778
```json
@@ -794,51 +811,8 @@ When a policy definition with `manual` effect is assigned, you have the option t
794811
### Attestations
795812

796813
`Microsoft.PolicyInsights/attestations`, called an Attestation resource, is a new proxy resource type
797-
that sets the compliance states for targeted resources in a manual policy. You can only have one
798-
attestation on one resource for an individual policy. In preview, Attestations are available
799-
only through the Azure Resource Manager (ARM) API.
800-
801-
Below is an example of creating a new attestation resource:
802-
803-
```http
804-
PUT http://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/attestations/{name}?api-version=2019-10-01
805-
```
806-
807-
#### Request body
808-
809-
Below is a sample attestation resource JSON object:
810-
811-
```json
812-
"properties": {
813-
"policyAssignmentId": "/subscriptions/{subscriptionID}/providers/microsoft.authorization/policyassignments/{assignmentID}",
814-
"policyDefinitionReferenceId": "{definitionReferenceID}",
815-
"complianceState": "Compliant",
816-
"expiresOn": "2023-07-14T00:00:00Z",
817-
"owner": "{AADObjectID}",
818-
"comments": "This subscription has passed a security audit. See attached details for evidence",
819-
"evidence": [
820-
{
821-
"description": "The results of the security audit.",
822-
"sourceUri": "https://gist.github.com/contoso/9573e238762c60166c090ae16b814011"
823-
},
824-
{
825-
"description": "Description of the attached evidence document.",
826-
"sourceUri": "https://storagesamples.blob.core.windows.net/sample-container/contingency_evidence_adendum.docx"
827-
},
828-
],
829-
}
830-
```
831-
832-
|Property |Description |
833-
|---------|---------|
834-
|policyAssignmentId |Required assignment ID for which the state is being set. |
835-
|policyDefinitionReferenceId |Optional definition reference ID, if within a policy initiative. |
836-
|complianceState |Desired state of the resources. Allowed values are `Compliant`, `NonCompliant`, and `Unknown`. |
837-
|owner |Optional Azure AD object ID of responsible party. |
838-
|comments |Optional description of why state is being set. |
839-
|evidence |Optional link array for attestation evidence. |
840-
841-
Because attestations are a separate resource from policy assignments, they have their own lifecycle. You can PUT, GET and DELETE attestations by using the ARM API. See the [Policy REST API Reference](/rest/api/policy) for more details.
814+
that sets the compliance states for targeted resources in a manual policy. Learn more about
815+
the attestation resource by reading [Azure Policy attestation structure](attestation-structure.md).
842816

843817
## Modify
844818

‎articles/governance/policy/toc.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,9 @@
196196
- name: Policy applicability
197197
displayName: policy, applicability, scope
198198
href: ./concepts/policy-applicability.md
199+
- name: Policy attestation
200+
displayName: manual policy, compliance, attestation
201+
href: ./concepts/attestation-structure.md
199202
- name: React to policy state change events
200203
displayName: event grid, subject, topic, subscription
201204
href: ./concepts/event-overview.md

0 commit comments

Comments
 (0)