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

ListControls

Returns a list of controls from AWS Audit Manager.

Request Syntax


GET /controls?controlCatalogId=controlCatalogId&controlType=controlType&maxResults=maxResults&nextToken=nextToken HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

controlCatalogId

A filter that narrows the list of controls to a specific resource from the AWS Control Catalog.

To use this parameter, specify the ARN of the Control Catalog resource. You can specify either a control domain, a control objective, or a common control. For information about how to find the ARNs for these resources, see ListDomains, ListObjectives, and ListCommonControls.

Note

You can only filter by one Control Catalog resource at a time. Specifying multiple resource ARNs isn’t currently supported. If you want to filter by more than one ARN, we recommend that you run the ListControls operation separately for each ARN.

Alternatively, specify UNCATEGORIZED to list controls that aren't mapped to a Control Catalog resource. For example, this operation might return a list of custom controls that don't belong to any control domain or control objective.

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

Pattern: ^arn:.*:controlcatalog:.*|UNCATEGORIZED

controlType

A filter that narrows the list of controls to a specific type.

Valid Values: Standard | Custom | Core

Required: Yes

maxResults

The maximum number of results on a page or for an API request call.

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

nextToken

The pagination token that's used to fetch the next set of results.

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

Pattern: ^[A-Za-z0-9+\/=]*$

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "controlMetadataList": [ 
      { 
         "arn": "string",
         "controlSources": "string",
         "createdAt": number,
         "id": "string",
         "lastUpdatedAt": number,
         "name": "string"
      }
   ],
   "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.

controlMetadataList

A list of metadata that the ListControls API returns for each control.

Type: Array of ControlMetadata objects

nextToken

The pagination token that's used to fetch the next set of results.

Type: String

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

Pattern: ^[A-Za-z0-9+\/=]*$

Errors

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

AccessDeniedException

Your account isn't registered with AWS Audit Manager. Check the delegated administrator setup on the 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

ValidationException

The request has invalid or missing parameters.

HTTP Status Code: 400

Examples

Retrieving a list of custom controls

This shows a sample response that the ListControls operation might return if you had three custom controls.

Sample Response


{
    "controlMetadataList": [
        {
            "arn": "arn:aws:auditmanager:us-east-1:111122223333:control/a1b2c3d4-5678-90ab-cdef-example11111",
            "id": "a1b2c3d4-5678-90ab-cdef-example11111",
            "name": "Example custom control",
            "controlSources": "AWS API calls, AWS Config, Manual",
            "createdAt": "2022-03-28T18:08:24.446000-07:00",
            "lastUpdatedAt": "2022-03-28T18:08:24.446000-07:00"
        },
        {
            "arn": "arn:aws:auditmanager:us-east-1:111122223333:control/a1b2c3d4-5678-90ab-cdef-example22222",
            "id": "a1b2c3d4-5678-90ab-cdef-example22222",
            "name": "Another custom control",
            "controlSources": "AWS API calls, AWS Config, Manual",
            "createdAt": "2022-03-28T17:45:15.622000-07:00",
            "lastUpdatedAt": "2022-03-28T18:06:56.171000-07:00"
        },
        {
            "arn": "arn:aws:auditmanager:us-east-1:111122223333:control/a1b2c3d4-5678-90ab-cdef-example33333",
            "id": "a1b2c3d4-5678-90ab-cdef-example33333",
            "name": "Custom control - CloudTrail Volume Events",
            "controlSources": "AWS CloudTrail",
            "createdAt": "2021-03-08T11:31:12.468000-08:00",
            "lastUpdatedAt": "2022-01-10T14:13:37.979000-08:00"
        }
    ]
}

Retrieving a list of core controls

This example shows how you can use the ListControls operation to return a filtered list of core controls that fall under a specific control domain (Asset management).

To retrieve a list of core controls

Use the ListDomains operation to see the control domains that you can use as filters. Find the control domain that you want to use as a filter (Asset management), and take note of its ARN.
Use the ListControls operation and use the following attributes as filters:
- Use ControlType and specify Core as the value.
- Use ControlCatalogId and specify the control domain ARN that you got from step 1.

The sample request uses the following ARN as a filter:

This ARN represents the Asset management control domain: arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq

The sample response shows the results that the ListControls operation might return if two core controls matched the domain criteria of Asset management.

Sample Request


aws auditmanager list-controls --controlType Core --controlCatalogId "arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq"

Sample Response


{
   "controlMetadataList": [ 
    {
        "arn": "arn:aws:auditmanager:us-west-2::control/a1b2c3d4-5678-90ab-cdef-example11111",
        "controlSources": "Manual",
        "createdAt": 1.681511681787E9,
        "id": "a1b2c3d4-5678-90ab-cdef-example11111",
        "lastUpdatedAt": 1.681511681788E9,
        "name": "164.312(a)(2)(iii)"
    }, {
        "arn": "arn:aws:auditmanager:us-west-2::control/a1b2c3d4-5678-90ab-cdef-example22222",
        "controlSources": "AWS API calls, AWS Config, AWS Security Hub",
        "createdAt": 1.681511681787E9,
        "id": "a1b2c3d4-5678-90ab-cdef-example22222",
        "lastUpdatedAt": 1.681511681788E9,
        "name": "164.312(c)(1)"
   } ],
   "nextToken": "string"
}