AWS Audit Manager

(1)

AWS Audit Manager

API Reference

API Version 2017-07-25

(2)

AWS Audit Manager: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

Welcome to the AWS Audit Manager API reference. This guide is for developers who need detailed information about the AWS Audit Manager API operations, data types, and errors.

AWS Audit Manager is a service that provides automated evidence collection so that you can continually audit your AWS usage. You can use it to assess the eﬀectiveness of your controls, manage risk, and simplify compliance.

AWS Audit Manager provides prebuilt frameworks that structure and automate assessments for a given compliance standard. Frameworks include a prebuilt collection of controls with descriptions and testing procedures. These controls are grouped according to the requirements of the speciﬁed compliance standard or regulation. You can also customize frameworks and controls to support internal audits with speciﬁc requirements.

Use the following links to get started with the AWS Audit Manager API:

• Actions: An alphabetical list of all AWS Audit Manager API operations.

• Data types: An alphabetical list of all AWS Audit Manager data types.

• Common parameters: Parameters that all Query operations can use.

• Common errors: Client and server errors that all operations can return.

If you're new to AWS Audit Manager, we recommend that you review the AWS Audit Manager User Guide.

This document was last published on March 6, 2022.

API Version 2017-07-25 1

(16)

Actions

The following actions are supported:

• AssociateAssessmentReportEvidenceFolder (p. 4)

• BatchAssociateAssessmentReportEvidence (p. 6)

• BatchCreateDelegationByAssessment (p. 9)

• BatchDeleteDelegationByAssessment (p. 12)

• BatchDisassociateAssessmentReportEvidence (p. 15)

• BatchImportEvidenceToAssessmentControl (p. 18)

• CreateAssessment (p. 21)

• CreateAssessmentFramework (p. 27)

• CreateAssessmentReport (p. 31)

• CreateControl (p. 34)

• DeleteAssessment (p. 38)

• DeleteAssessmentFramework (p. 40)

• DeleteAssessmentFrameworkShare (p. 42)

• DeleteAssessmentReport (p. 44)

• DeleteControl (p. 46)

• DeregisterAccount (p. 48)

• DeregisterOrganizationAdminAccount (p. 50)

• DisassociateAssessmentReportEvidenceFolder (p. 52)

• GetAccountStatus (p. 54)

• GetAssessment (p. 56)

• GetAssessmentFramework (p. 60)

• GetAssessmentReportUrl (p. 63)

• GetChangeLogs (p. 65)

• GetControl (p. 68)

• GetDelegations (p. 71)

• GetEvidence (p. 73)

• GetEvidenceByEvidenceFolder (p. 76)

• GetEvidenceFolder (p. 79)

• GetEvidenceFoldersByAssessment (p. 82)

• GetEvidenceFoldersByAssessmentControl (p. 85)

• GetInsights (p. 88)

• GetInsightsByAssessment (p. 90)

• GetOrganizationAdminAccount (p. 92)

• GetServicesInScope (p. 94)

• GetSettings (p. 96)

• ListAssessmentControlInsightsByControlDomain (p. 98)

• ListAssessmentFrameworks (p. 101)

• ListAssessmentFrameworkShareRequests (p. 104)

• ListAssessmentReports (p. 107)

• ListAssessments (p. 109)

(17)

• ListControlDomainInsights (p. 112)

• ListControlDomainInsightsByAssessment (p. 115)

• ListControlInsightsByControlDomain (p. 118)

• ListControls (p. 121)

• ListKeywordsForDataSource (p. 124)

• ListNotiﬁcations (p. 126)

• ListTagsForResource (p. 128)

• RegisterAccount (p. 130)

• RegisterOrganizationAdminAccount (p. 133)

• StartAssessmentFrameworkShare (p. 135)

• TagResource (p. 138)

• UntagResource (p. 140)

• UpdateAssessment (p. 142)

• UpdateAssessmentControl (p. 147)

• UpdateAssessmentControlSetStatus (p. 150)

• UpdateAssessmentFramework (p. 153)

• UpdateAssessmentFrameworkShare (p. 157)

• UpdateAssessmentStatus (p. 160)

• UpdateControl (p. 164)

• UpdateSettings (p. 168)

• ValidateAssessmentReportIntegrity (p. 171)

(18)

AssociateAssessmentReportEvidenceFolder

Associates an evidence folder to an assessment report in a AWS Audit Manager assessment.

Request Syntax

PUT /assessments/assessmentId/associateToAssessmentReport HTTP/1.1 Content-type: application/json

{

"evidenceFolderId": "string"

}

URI Request Parameters

The request uses the following URI parameters.

assessmentId (p. 4)

The identiﬁer for the assessment.

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

Request Body

The request accepts the following data in JSON format.

evidenceFolderId (p. 4)

The identiﬁer for the folder that the evidence is stored in.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

(19)

Errors

For information about the errors that are common to all actions, see Common Errors (p. 265).

AccessDeniedException

Your account isn't registered with AWS Audit Manager. Check the delegated administrator setup on the AWS Audit Manager settings page, and try again.

HTTP Status Code: 403 InternalServerException

An internal service error occurred during the processing of your request. Try again later.

HTTP Status Code: 500 ResourceNotFoundException

The resource that's speciﬁed in the request can't be found.

HTTP Status Code: 404 ValidationException

The request has invalid or missing parameters.

HTTP Status Code: 400

BatchAssociateAssessmentReportEvidence

Associates a list of evidence to an assessment report in an AWS Audit Manager assessment.

Request Syntax

PUT /assessments/assessmentId/batchAssociateToAssessmentReport HTTP/1.1 Content-type: application/json

{

"evidenceFolderId": "string", "evidenceIds": [ "string" ] }

URI Request Parameters

Required: Yes

Request Body

Type: String

Required: Yes evidenceIds (p. 6)

The list of evidence identiﬁers.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: Yes

(21)

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"errors": [ {

"errorCode": "string", "errorMessage": "string", "evidenceId": "string"

} ],

"evidenceIds": [ "string" ] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

errors (p. 7)

A list of errors that the BatchAssociateAssessmentReportEvidence API returned.

Type: Array of AssessmentReportEvidenceError (p. 199) objects evidenceIds (p. 7)

Errors

(22)

BatchCreateDelegationByAssessment

Creates a batch of delegations for an assessment in AWS Audit Manager.

Request Syntax

POST /assessments/assessmentId/delegations HTTP/1.1 Content-type: application/json

{

"createDelegationRequests": [ {

"comment": "string", "controlSetId": "string", "roleArn": "string", "roleType": "string"

} ] }

URI Request Parameters

Required: Yes

Request Body

createDelegationRequests (p. 9)

The API request to batch create delegations in AWS Audit Manager.

Type: Array of CreateDelegationRequest (p. 228) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "delegations": [

(24)

Response Elements

{

"assessmentId": "string", "assessmentName": "string", "comment": "string",

"controlSetId": "string", "createdBy": "string", "creationTime": number, "id": "string",

"lastUpdated": number, "roleArn": "string", "roleType": "string", "status": "string"

} ],

"errors": [ {

"createDelegationRequest": { "comment": "string", "controlSetId": "string", "roleArn": "string", "roleType": "string"

},

"errorCode": "string", "errorMessage": "string"

} ] }

Response Elements

delegations (p. 9)

The delegations that are associated with the assessment.

Type: Array of Delegation (p. 230) objects errors (p. 9)

A list of errors that the BatchCreateDelegationByAssessment API returned.

Type: Array of BatchCreateDelegationByAssessmentError (p. 205) objects

Errors

(25)

ResourceNotFoundException

BatchDeleteDelegationByAssessment

Deletes a batch of delegations for an assessment in AWS Audit Manager.

Request Syntax

PUT /assessments/assessmentId/delegations HTTP/1.1 Content-type: application/json

{

"delegationIds": [ "string" ] }

URI Request Parameters

Required: Yes

Request Body

delegationIds (p. 12)

The identiﬁers for the delegations.

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "errors": [

{

"delegationId": "string",

(27)

"errorCode": "string", "errorMessage": "string"

} ] }

Response Elements

errors (p. 12)

A list of errors that the BatchDeleteDelegationByAssessment API returned.

Type: Array of BatchDeleteDelegationByAssessmentError (p. 206) objects

Errors

BatchDisassociateAssessmentReportEvidence

Disassociates a list of evidence from an assessment report in AWS Audit Manager.

Request Syntax

PUT /assessments/assessmentId/batchDisassociateFromAssessmentReport HTTP/1.1 Content-type: application/json

{

"evidenceFolderId": "string", "evidenceIds": [ "string" ] }

URI Request Parameters

Required: Yes

Request Body

Type: String

Required: Yes evidenceIds (p. 15)

Required: Yes

(30)

Response Syntax

HTTP/1.1 200

"errors": [ {

"errorCode": "string", "errorMessage": "string", "evidenceId": "string"

} ],

"evidenceIds": [ "string" ] }

Response Elements

errors (p. 16)

A list of errors that the BatchDisassociateAssessmentReportEvidence API returned.

Type: Array of AssessmentReportEvidenceError (p. 199) objects evidenceIds (p. 16)

The identiﬁer for the evidence.

Errors

(31)

BatchImportEvidenceToAssessmentControl

Uploads one or more pieces of evidence to a control in an AWS Audit Manager assessment.

Request Syntax

POST /assessments/assessmentId/controlSets/controlSetId/controls/controlId/evidence HTTP/1.1

"manualEvidence": [ {

"s3ResourcePath": "string"

} ] }

URI Request Parameters

Required: Yes controlId (p. 18)

The identiﬁer for the control.

Required: Yes controlSetId (p. 18)

The identiﬁer for the control set.

Length Constraints: Minimum length of 1. Maximum length of 300.

Pattern: ^[\w\W\s\S]*$

Required: Yes

Request Body

manualEvidence (p. 18)

The list of manual evidence objects.

(33)

Type: Array of ManualEvidence (p. 249) objects

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "errors": [

{

"errorCode": "string", "errorMessage": "string", "manualEvidence": {

"s3ResourcePath": "string"

} } ]}

Response Elements

errors (p. 19)

A list of errors that the BatchImportEvidenceToAssessmentControl API returned.

Type: Array of BatchImportEvidenceToAssessmentControlError (p. 207) objects

Errors

(34)

CreateAssessment

Creates an assessment in AWS Audit Manager.

Request Syntax

POST /assessments HTTP/1.1 Content-type: application/json { "assessmentReportsDestination": { "destination": "string",

"destinationType": "string"

},

"description": "string", "frameworkId": "string", "name": "string",

"roles": [ {

"roleArn": "string", "roleType": "string"

} ],

"scope": {

"awsAccounts": [ {

"emailAddress": "string", "id": "string",

"name": "string"

} ],

"awsServices": [ {

"serviceName": "string"

} ] },

"tags": {

"string" : "string"

}}

URI Request Parameters

The request does not use any URI parameters.

Request Body

assessmentReportsDestination (p. 21)

The assessment report storage destination for the assessment that's being created.

Type: AssessmentReportsDestination (p. 202) object Required: Yes

(36)

Request Body

description (p. 21)

The optional description of the assessment to be created.

Type: String

Length Constraints: Maximum length of 1000.

Required: No frameworkId (p. 21)

The identiﬁer for the framework that the assessment will be created from.

Type: String

Required: Yes name (p. 21)

The name of the assessment to be created.

Type: String

Pattern: ^[^\\]*$

Required: Yes roles (p. 21)

The list of roles for the assessment.

Type: Array of Role (p. 253) objects Required: Yes

scope (p. 21)

The wrapper that contains the AWS accounts and services that are in scope for the assessment.

Type: Scope (p. 254) object Required: Yes

tags (p. 21)

The tags that are associated with the assessment.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^(?!aws:)[a-zA-Z+-=._:/]+$

(37)

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: .{0,255}

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json { "assessment": {

"arn": "string", "awsAccount": {

"name": "string"

},

"framework": { "arn": "string", "controlSets": [ {

"controls": [ {

"assessmentReportEvidenceCount": number, "comments": [

{

"authorName": "string", "commentBody": "string", "postedDate": number }

],

"description": "string", "evidenceCount": number,

"evidenceSources": [ "string" ], "id": "string",

"name": "string", "response": "string", "status": "string"

} ],

"delegations": [ {

} ],

"description": "string", "id": "string",

"manualEvidenceCount": number, "roles": [

{

"roleArn": "string",

(38)

Response Syntax

"roleType": "string"

} ],

"status": "string",

"systemEvidenceCount": number }

],

"id": "string", "metadata": {

"complianceType": "string", "description": "string", "logo": "string",

"name": "string"

} },

"metadata": {

"assessmentReportsDestination": { "destination": "string", "destinationType": "string"

},

"complianceType": "string", "creationTime": number, "delegations": [ {

} ],

"description": "string", "id": "string",

"lastUpdated": number, "name": "string", "roles": [ {

"roleArn": "string", "roleType": "string"

} ],

"scope": {

"awsAccounts": [ {

"name": "string"

} ],

"awsServices": [ {

"serviceName": "string"

} ] },

"status": "string"

},

"tags": {

"string" : "string"

}

(39)

} }

Response Elements

assessment (p. 23)

An entity that deﬁnes the scope of audit evidence collected by AWS Audit Manager. An AWS Audit Manager assessment is an implementation of an AWS Audit Manager framework.

Type: Assessment (p. 176) object

Errors

CreateAssessmentFramework

Creates a custom framework in AWS Audit Manager.

Request Syntax

POST /assessmentFrameworks HTTP/1.1 Content-type: application/json { "complianceType": "string", "controlSets": [

{

"controls": [ {

"id": "string"

} ],

"name": "string"

} ],

"description": "string", "name": "string",

"tags": {

"string" : "string"

}}

URI Request Parameters

Request Body

complianceType (p. 27)

The compliance type that the new custom framework supports, such as CIS or HIPAA.

Type: String

Required: No controlSets (p. 27)

The control sets that are associated with the framework.

Type: Array of CreateAssessmentFrameworkControlSet (p. 225) objects Array Members: Minimum number of 1 item.

Required: Yes

(42)

Response Syntax

An optional description for the new custom framework.

Type: String

Required: No name (p. 27)

The name of the new custom framework.

Type: String

Pattern: ^[^\\]*$

Required: Yes tags (p. 27)

The tags that are associated with the framework.

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json { "framework": {

"arn": "string",

"complianceType": "string", "controlSets": [

{

"controls": [ {

"actionPlanInstructions": "string", "actionPlanTitle": "string",

"arn": "string",

"controlMappingSources": [ {

"sourceDescription": "string", "sourceFrequency": "string",

(43)

"sourceId": "string", "sourceKeyword": {

"keywordInputType": "string", "keywordValue": "string"

},

"sourceName": "string", "sourceSetUpOption": "string", "sourceType": "string",

"troubleshootingText": "string"

} ],

"controlSources": "string", "createdAt": number, "createdBy": "string", "description": "string", "id": "string",

"lastUpdatedAt": number, "lastUpdatedBy": "string", "name": "string",

"tags": {

},

"testingInformation": "string", "type": "string"

} ],

"id": "string", "name": "string"

} ],

"lastUpdatedAt": number, "lastUpdatedBy": "string", "logo": "string",

"name": "string", "tags": {

},

"type": "string"

} }

Response Elements

framework (p. 28)

The name of the new framework that the CreateAssessmentFramework API returned.

Type: Framework (p. 240) object

Errors

(44)

CreateAssessmentReport

Creates an assessment report for the speciﬁed assessment.

Request Syntax

POST /assessments/assessmentId/reports HTTP/1.1 Content-type: application/json

{ "description": "string", "name": "string"

}

URI Request Parameters

Required: Yes

Request Body

The description of the assessment report.

Type: String

The name of the new assessment report.

Type: String

Pattern: ^[a-zA-Z0-9-_\.]+$

Required: Yes

(46)

Response Syntax

HTTP/1.1 200

"assessmentReport": { "assessmentId": "string", "assessmentName": "string", "author": "string",

"awsAccountId": "string", "creationTime": number, "description": "string", "id": "string",

"name": "string", "status": "string"

}}

Response Elements

assessmentReport (p. 32)

The new assessment report that the CreateAssessmentReport API returned.

Type: AssessmentReport (p. 197) object

Errors

(47)

CreateControl

Creates a new custom control in AWS Audit Manager.

Request Syntax

POST /controls HTTP/1.1

"actionPlanInstructions": "string", "actionPlanTitle": "string",

"sourceDescription": "string", "sourceFrequency": "string", "sourceKeyword": {

},

"sourceName": "string", "sourceSetUpOption": "string", "sourceType": "string",

} ],

"description": "string", "name": "string",

"tags": {

"string" : "string"

},

"testingInformation": "string"

}

URI Request Parameters

Request Body

actionPlanInstructions (p. 34)

The recommended actions to carry out if the control isn't fulﬁlled.

Type: String

Required: No actionPlanTitle (p. 34)

The title of the action plan for remediating the control.

Type: String

(49)

Required: No

controlMappingSources (p. 34)

The data mapping sources for the control.

Type: Array of CreateControlMappingSource (p. 226) objects Array Members: Minimum number of 1 item.

Required: Yes description (p. 34)

The description of the control.

Type: String

The name of the control.

Type: String

Pattern: ^[^\\]*$

Required: Yes tags (p. 34)

The tags that are associated with the control.

Required: No

testingInformation (p. 34)

The steps to follow to determine if the control is satisﬁed.

Type: String

(50)

Response Syntax

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json { "control": {

"actionPlanInstructions": "string", "actionPlanTitle": "string", "arn": "string",

"sourceDescription": "string", "sourceFrequency": "string", "sourceId": "string", "sourceKeyword": {

},

"sourceName": "string",

"sourceSetUpOption": "string", "sourceType": "string",

} ],

"lastUpdatedAt": number, "lastUpdatedBy": "string", "name": "string",

"tags": {

},

"testingInformation": "string", "type": "string"

}}

Response Elements

control (p. 36)

The new control that the CreateControl API returned.

Type: Control (p. 210) object

Errors

(51)

DeleteAssessment

Deletes an assessment in AWS Audit Manager.

Request Syntax

DELETE /assessments/assessmentId HTTP/1.1

URI Request Parameters

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(53)

DeleteAssessmentFramework

Deletes a custom framework in AWS Audit Manager.

Request Syntax

DELETE /assessmentFrameworks/frameworkId HTTP/1.1

URI Request Parameters

frameworkId (p. 40)

The identiﬁer for the custom framework.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

AWS Audit Manager

AWS Audit Manager

API Reference

API Version 2017-07-25

AWS Audit Manager: API Reference

Table of Contents

Welcome

Actions

AssociateAssessmentReportEvidenceFolder

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchAssociateAssessmentReportEvidence

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchCreateDelegationByAssessment

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchDeleteDelegationByAssessment

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchDisassociateAssessmentReportEvidence

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

BatchImportEvidenceToAssessmentControl

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateAssessment

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateAssessmentFramework

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateAssessmentReport

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also