Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

DescribeAssessment

Returns the metadata and detailed results of a single assessment, including the framework that was evaluated, the overall assessment result, and a paginated list of individual control evaluation results.

To list available assessments before describing one, use the ListAssessments action.

Request Syntax


POST /DescribeAssessment HTTP/1.1
Content-type: application/json

{
   "AssessmentIdentifier": "string",
   "Catalog": "string",
   "MaxResults": number,
   "NextToken": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

AssessmentIdentifier

The unique identifier of the assessment to describe. You can provide either the assessment ID (for example, assessment-12345) or the full assessment ARN (for example, arn:aws:aws-marketplace:us-east-1::AWSMarketplace/Assessment/assessment-12345).

Type: String

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

Pattern: ^(assessment-[a-zA-Z0-9]+|arn:[a-zA-Z0-9-]+:[a-zA-Z0-9-]+:[a-zA-Z0-9-]*:[0-9]*:[a-zA-Z0-9-]+/Assessment/assessment-[a-zA-Z0-9]+)$

Required: Yes

Catalog

The catalog related to the request. Fixed value: AWSMarketplace

Type: String

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

Pattern: ^[a-zA-Z]+$

Required: Yes

MaxResults

Specifies the upper limit of ControlAssessment elements returned on a single page. If a value isn't provided, the default value is 50. Valid values range from 1 to 100.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

NextToken

The value of the next token, if it exists. null if there are no more results.

Type: String

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

Pattern: ^[\w+=.:@\-\/]+$

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "AssessmentArn": "string",
   "AssessmentId": "string",
   "AssessmentResult": "string",
   "AssessmentTargetSummary": { 
      "ChangeSetId": "string",
      "EntityId": "string"
   },
   "ControlAssessments": [ 
      { 
         "ControlAssessmentResult": "string",
         "ControlId": "string",
         "Errors": [ 
            { 
               "Code": "string",
               "Message": "string",
               "Scope": [ 
                  { 
                     "Name": "string",
                     "Value": "string"
                  }
               ]
            }
         ]
      }
   ],
   "CreatedAt": "string",
   "ExpiresAt": "string",
   "FrameworkId": "string",
   "FrameworkSummary": { ... },
   "NextToken": "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.

AssessmentArn

The ARN associated with the assessment.

Type: String

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

Pattern: ^[a-zA-Z0-9:*/-]+$

AssessmentId

The unique ID of the assessment.

Type: String

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

Pattern: ^[\w\-]+$

AssessmentResult

The overall result of the assessment.

Type: String

Valid Values: PASS | FAIL

AssessmentTargetSummary

Identifies the entity or change set that was assessed.

Type: AssessmentTargetSummary object

ControlAssessments

An array of ControlAssessment objects, each containing the result of an individual control evaluated as part of the assessment.

Type: Array of ControlAssessment objects

CreatedAt

The date and time the assessment was created, in ISO 8601 format (2018-02-27T13:45:22Z).

Type: String

Length Constraints: Fixed length of 20.

Pattern: ^([\d]{4})\-(1[0-2]|0[1-9])\-(3[01]|0[1-9]|[12][\d])T(2[0-3]|[01][\d]):([0-5][\d]):([0-5][\d])Z$

ExpiresAt

The date and time the assessment expires, in ISO 8601 format (2018-02-27T13:45:22Z).

Type: String

Length Constraints: Fixed length of 20.

Pattern: ^([\d]{4})\-(1[0-2]|0[1-9])\-(3[01]|0[1-9]|[12][\d])T(2[0-3]|[01][\d]):([0-5][\d]):([0-5][\d])Z$

FrameworkId

The identifier of the framework that was evaluated by this assessment, in the format frameworkId@version (for example, AMISecurity@1.0).

Type: String

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

Pattern: ^[\w\-@.]+$

FrameworkSummary

The framework-specific details of the assessed resource. The set member corresponds to the framework identified by FrameworkId.

Type: FrameworkSummary object

Note: This object is a Union. Only one member of this object can be specified or returned.

NextToken

The value of the next token, if it exists. null if there are no more results.

Type: String

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

Pattern: ^[\w+=.:@\-\/]+$

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

Access is denied.

HTTP status code: 403

HTTP Status Code: 403

InternalServiceException

There was an internal service exception.

HTTP status code: 500

HTTP Status Code: 500

ResourceNotFoundException

The specified resource wasn't found.

HTTP status code: 404

HTTP Status Code: 404

ThrottlingException

Too many requests.

HTTP status code: 429

HTTP Status Code: 429

ValidationException

An error occurred during validation.

HTTP status code: 422

HTTP Status Code: 422