Returns details about a specific control, most notably a list of Amazon Web Services Regions where this control is supported. Input a value for the ControlArn parameter, in ARN form. GetControl accepts controltower or controlcatalog control ARNs as input. Returns a controlcatalog ARN format.
In the API response, controls that have the value GLOBAL in the Scope field do not show the DeployableRegions field, because it does not apply. Controls that have the value REGIONAL in the Scope field return a value for the DeployableRegions field, as shown in the example.
Returns a paginated list of common controls from the Amazon Web Services Control Catalog.
You can apply an optional filter to see common controls that have a specific objective. If you don’t provide a filter, the operation returns all common controls.
" }, "ListControls":{ "name":"ListControls", "http":{ "method":"POST", "requestUri":"/list-controls", "responseCode":200 }, "input":{"shape":"ListControlsRequest"}, "output":{"shape":"ListControlsResponse"}, "errors":[ {"shape":"AccessDeniedException"}, {"shape":"InternalServerException"}, {"shape":"ValidationException"}, {"shape":"ThrottlingException"} ], "documentation":"Returns a paginated list of all available controls in the Amazon Web Services Control Catalog library. Allows you to discover available controls. The list of controls is given as structures of type controlSummary. The ARN is returned in the global controlcatalog format, as shown in the examples.
" }, "ListDomains":{ "name":"ListDomains", "http":{ "method":"POST", "requestUri":"/domains", "responseCode":200 }, "input":{"shape":"ListDomainsRequest"}, "output":{"shape":"ListDomainsResponse"}, "errors":[ {"shape":"AccessDeniedException"}, {"shape":"InternalServerException"}, {"shape":"ValidationException"}, {"shape":"ThrottlingException"} ], "documentation":"Returns a paginated list of domains from the Amazon Web Services Control Catalog.
" }, "ListObjectives":{ "name":"ListObjectives", "http":{ "method":"POST", "requestUri":"/objectives", "responseCode":200 }, "input":{"shape":"ListObjectivesRequest"}, "output":{"shape":"ListObjectivesResponse"}, "errors":[ {"shape":"AccessDeniedException"}, {"shape":"InternalServerException"}, {"shape":"ValidationException"}, {"shape":"ThrottlingException"} ], "documentation":"Returns a paginated list of objectives from the Amazon Web Services Control Catalog.
You can apply an optional filter to see the objectives that belong to a specific domain. If you don’t provide a filter, the operation returns all objectives.
" } }, "shapes":{ "AccessDeniedException":{ "type":"structure", "members":{ "Message":{"shape":"String"} }, "documentation":"You do not have sufficient access to perform this action.
", "error":{ "httpStatusCode":403, "senderFault":true }, "exception":true }, "AssociatedDomainSummary":{ "type":"structure", "members":{ "Arn":{ "shape":"DomainArn", "documentation":"The Amazon Resource Name (ARN) of the related domain.
" }, "Name":{ "shape":"String", "documentation":"The name of the related domain.
" } }, "documentation":"A summary of the domain that a common control or an objective belongs to.
" }, "AssociatedObjectiveSummary":{ "type":"structure", "members":{ "Arn":{ "shape":"ObjectiveArn", "documentation":"The Amazon Resource Name (ARN) of the related objective.
" }, "Name":{ "shape":"String", "documentation":"The name of the related objective.
" } }, "documentation":"A summary of the objective that a common control supports.
" }, "CommonControlArn":{ "type":"string", "max":2048, "min":41, "pattern":"arn:(aws(?:[-a-z]*)?):controlcatalog:::common-control/[0-9a-z]+" }, "CommonControlFilter":{ "type":"structure", "members":{ "Objectives":{ "shape":"ObjectiveResourceFilterList", "documentation":"The objective that's used as filter criteria.
You can use this parameter to specify one objective ARN at a time. Passing multiple ARNs in the CommonControlFilter isn’t currently supported.
An optional filter that narrows the results to a specific objective.
" }, "CommonControlSummary":{ "type":"structure", "required":[ "Arn", "Name", "Description", "Domain", "Objective", "CreateTime", "LastUpdateTime" ], "members":{ "Arn":{ "shape":"CommonControlArn", "documentation":"The Amazon Resource Name (ARN) that identifies the common control.
" }, "Name":{ "shape":"String", "documentation":"The name of the common control.
" }, "Description":{ "shape":"String", "documentation":"The description of the common control.
" }, "Domain":{ "shape":"AssociatedDomainSummary", "documentation":"The domain that the common control belongs to.
" }, "Objective":{ "shape":"AssociatedObjectiveSummary", "documentation":"The objective that the common control belongs to.
" }, "CreateTime":{ "shape":"Timestamp", "documentation":"The time when the common control was created.
" }, "LastUpdateTime":{ "shape":"Timestamp", "documentation":"The time when the common control was most recently updated.
" } }, "documentation":"A summary of metadata for a common control.
" }, "CommonControlSummaryList":{ "type":"list", "member":{"shape":"CommonControlSummary"} }, "ControlArn":{ "type":"string", "max":2048, "min":34, "pattern":"arn:(aws(?:[-a-z]*)?):(controlcatalog|controltower):[a-zA-Z0-9-]*::control/[0-9a-zA-Z_\\-]+" }, "ControlBehavior":{ "type":"string", "enum":[ "PREVENTIVE", "PROACTIVE", "DETECTIVE" ] }, "ControlParameter":{ "type":"structure", "required":["Name"], "members":{ "Name":{ "shape":"String", "documentation":"The parameter name. This name is the parameter key when you call EnableControl or UpdateEnabledControl .
Four types of control parameters are supported.
AllowedRegions: List of Amazon Web Services Regions exempted from the control. Each string is expected to be an Amazon Web Services Region code. This parameter is mandatory for the OU Region deny control, CT.MULTISERVICE.PV.1.
Example: [\"us-east-1\",\"us-west-2\"]
ExemptedActions: List of Amazon Web Services IAM actions exempted from the control. Each string is expected to be an IAM action.
Example: [\"logs:DescribeLogGroups\",\"logs:StartQuery\",\"logs:GetQueryResults\"]
ExemptedPrincipalArns: List of Amazon Web Services IAM principal ARNs exempted from the control. Each string is expected to be an IAM principal that follows the pattern ^arn:(aws|aws-us-gov):(iam|sts)::.+:.+$
Example: [\"arn:aws:iam::*:role/ReadOnly\",\"arn:aws:sts::*:assumed-role/ReadOnly/*\"]
ExemptedResourceArns: List of resource ARNs exempted from the control. Each string is expected to be a resource ARN.
Example: [\"arn:aws:s3:::my-bucket-name\"]
The Amazon Resource Name (ARN) of the control.
" }, "Name":{ "shape":"String", "documentation":"The display name of the control.
" }, "Description":{ "shape":"String", "documentation":"A description of the control, as it may appear in the console. Describes the functionality of the control.
" } }, "documentation":"Overview of information about a control.
" }, "Controls":{ "type":"list", "member":{"shape":"ControlSummary"} }, "DeployableRegions":{ "type":"list", "member":{"shape":"RegionCode"} }, "DomainArn":{ "type":"string", "max":2048, "min":33, "pattern":"arn:(aws(?:[-a-z]*)?):controlcatalog:::domain/[0-9a-z]+" }, "DomainResourceFilter":{ "type":"structure", "members":{ "Arn":{ "shape":"DomainArn", "documentation":"The Amazon Resource Name (ARN) of the domain.
" } }, "documentation":"The domain resource that's being used as a filter.
" }, "DomainResourceFilterList":{ "type":"list", "member":{"shape":"DomainResourceFilter"} }, "DomainSummary":{ "type":"structure", "required":[ "Arn", "Name", "Description", "CreateTime", "LastUpdateTime" ], "members":{ "Arn":{ "shape":"DomainArn", "documentation":"The Amazon Resource Name (ARN) that identifies the domain.
" }, "Name":{ "shape":"String", "documentation":"The name of the domain.
" }, "Description":{ "shape":"String", "documentation":"The description of the domain.
" }, "CreateTime":{ "shape":"Timestamp", "documentation":"The time when the domain was created.
" }, "LastUpdateTime":{ "shape":"Timestamp", "documentation":"The time when the domain was most recently updated.
" } }, "documentation":"A summary of metadata for a domain.
" }, "DomainSummaryList":{ "type":"list", "member":{"shape":"DomainSummary"} }, "GetControlRequest":{ "type":"structure", "required":["ControlArn"], "members":{ "ControlArn":{ "shape":"ControlArn", "documentation":"The Amazon Resource Name (ARN) of the control. It has one of the following formats:
Global format
arn:{PARTITION}:controlcatalog:::control/{CONTROL_CATALOG_OPAQUE_ID}
Or Regional format
arn:{PARTITION}:controltower:{REGION}::control/{CONTROL_TOWER_OPAQUE_ID}
Here is a more general pattern that covers Amazon Web Services Control Tower and Control Catalog ARNs:
^arn:(aws(?:[-a-z]*)?):(controlcatalog|controltower):[a-zA-Z0-9-]*::control/[0-9a-zA-Z_\\\\-]+$
The Amazon Resource Name (ARN) of the control.
" }, "Name":{ "shape":"String", "documentation":"The display name of the control.
" }, "Description":{ "shape":"String", "documentation":"A description of what the control does.
" }, "Behavior":{ "shape":"ControlBehavior", "documentation":"A term that identifies the control's functional behavior. One of Preventive, Detective, Proactive
Returns information about the control, as an ImplementationDetails object that shows the underlying implementation type for a control.
Returns an array of ControlParameter objects that specify the parameters a control supports. An empty list is returned for controls that don’t support parameters.
A string that describes a control's implementation type.
" } }, "documentation":"An object that describes the implementation type for a control.
Our ImplementationDetails Type format has three required segments:
SERVICE-PROVIDER::SERVICE-NAME::RESOURCE-NAME
For example, AWS::Config::ConfigRule or AWS::SecurityHub::SecurityControl resources have the format with three required segments.
Our ImplementationDetails Type format has an optional fourth segment, which is present for applicable implementation types. The format is as follows:
SERVICE-PROVIDER::SERVICE-NAME::RESOURCE-NAME::RESOURCE-TYPE-DESCRIPTION
For example, AWS::Organizations::Policy::SERVICE_CONTROL_POLICY or AWS::CloudFormation::Type::HOOK have the format with four segments.
Although the format is similar, the values for the Type field do not match any Amazon Web Services CloudFormation values.
An internal service error occurred during the processing of your request. Try again later.
", "error":{"httpStatusCode":500}, "exception":true, "fault":true, "retryable":{"throttling":false} }, "ListCommonControlsRequest":{ "type":"structure", "members":{ "MaxResults":{ "shape":"MaxListCommonControlsResults", "documentation":"The maximum number of results on a page or for an API request call.
", "location":"querystring", "locationName":"maxResults" }, "NextToken":{ "shape":"PaginationToken", "documentation":"The pagination token that's used to fetch the next set of results.
", "location":"querystring", "locationName":"nextToken" }, "CommonControlFilter":{ "shape":"CommonControlFilter", "documentation":"An optional filter that narrows the results to a specific objective.
This filter allows you to specify one objective ARN at a time. Passing multiple ARNs in the CommonControlFilter isn’t currently supported.
The list of common controls that the ListCommonControls API returns.
The pagination token that's used to fetch the next set of results.
" } } }, "ListControlsRequest":{ "type":"structure", "members":{ "NextToken":{ "shape":"PaginationToken", "documentation":"The pagination token that's used to fetch the next set of results.
", "location":"querystring", "locationName":"nextToken" }, "MaxResults":{ "shape":"MaxListControlsResults", "documentation":"The maximum number of results on a page or for an API request call.
", "location":"querystring", "locationName":"maxResults" } } }, "ListControlsResponse":{ "type":"structure", "required":["Controls"], "members":{ "Controls":{ "shape":"Controls", "documentation":"Returns a list of controls, given as structures of type controlSummary.
" }, "NextToken":{ "shape":"PaginationToken", "documentation":"The pagination token that's used to fetch the next set of results.
" } } }, "ListDomainsRequest":{ "type":"structure", "members":{ "MaxResults":{ "shape":"MaxListDomainsResults", "documentation":"The maximum number of results on a page or for an API request call.
", "location":"querystring", "locationName":"maxResults" }, "NextToken":{ "shape":"PaginationToken", "documentation":"The pagination token that's used to fetch the next set of results.
", "location":"querystring", "locationName":"nextToken" } } }, "ListDomainsResponse":{ "type":"structure", "required":["Domains"], "members":{ "Domains":{ "shape":"DomainSummaryList", "documentation":"The list of domains that the ListDomains API returns.
The pagination token that's used to fetch the next set of results.
" } } }, "ListObjectivesRequest":{ "type":"structure", "members":{ "MaxResults":{ "shape":"MaxListObjectivesResults", "documentation":"The maximum number of results on a page or for an API request call.
", "location":"querystring", "locationName":"maxResults" }, "NextToken":{ "shape":"PaginationToken", "documentation":"The pagination token that's used to fetch the next set of results.
", "location":"querystring", "locationName":"nextToken" }, "ObjectiveFilter":{ "shape":"ObjectiveFilter", "documentation":"An optional filter that narrows the results to a specific domain.
This filter allows you to specify one domain ARN at a time. Passing multiple ARNs in the ObjectiveFilter isn’t currently supported.
The list of objectives that the ListObjectives API returns.
The pagination token that's used to fetch the next set of results.
" } } }, "MaxListCommonControlsResults":{ "type":"integer", "box":true, "max":100, "min":1 }, "MaxListControlsResults":{ "type":"integer", "box":true, "max":100, "min":1 }, "MaxListDomainsResults":{ "type":"integer", "box":true, "max":100, "min":1 }, "MaxListObjectivesResults":{ "type":"integer", "box":true, "max":100, "min":1 }, "ObjectiveArn":{ "type":"string", "max":2048, "min":36, "pattern":"arn:(aws(?:[-a-z]*)?):controlcatalog:::objective/[0-9a-z]+" }, "ObjectiveFilter":{ "type":"structure", "members":{ "Domains":{ "shape":"DomainResourceFilterList", "documentation":"The domain that's used as filter criteria.
You can use this parameter to specify one domain ARN at a time. Passing multiple ARNs in the ObjectiveFilter isn’t currently supported.
An optional filter that narrows the list of objectives to a specific domain.
" }, "ObjectiveResourceFilter":{ "type":"structure", "members":{ "Arn":{ "shape":"ObjectiveArn", "documentation":"The Amazon Resource Name (ARN) of the objective.
" } }, "documentation":"The objective resource that's being used as a filter.
" }, "ObjectiveResourceFilterList":{ "type":"list", "member":{"shape":"ObjectiveResourceFilter"} }, "ObjectiveSummary":{ "type":"structure", "required":[ "Arn", "Name", "Description", "Domain", "CreateTime", "LastUpdateTime" ], "members":{ "Arn":{ "shape":"ObjectiveArn", "documentation":"The Amazon Resource Name (ARN) that identifies the objective.
" }, "Name":{ "shape":"String", "documentation":"The name of the objective.
" }, "Description":{ "shape":"String", "documentation":"The description of the objective.
" }, "Domain":{ "shape":"AssociatedDomainSummary", "documentation":"The domain that the objective belongs to.
" }, "CreateTime":{ "shape":"Timestamp", "documentation":"The time when the objective was created.
" }, "LastUpdateTime":{ "shape":"Timestamp", "documentation":"The time when the objective was most recently updated.
" } }, "documentation":"A summary of metadata for an objective.
" }, "ObjectiveSummaryList":{ "type":"list", "member":{"shape":"ObjectiveSummary"} }, "PaginationToken":{ "type":"string", "max":1024, "min":0 }, "RegionCode":{ "type":"string", "pattern":"[a-zA-Z0-9-]{1,128}" }, "RegionConfiguration":{ "type":"structure", "required":["Scope"], "members":{ "Scope":{ "shape":"ControlScope", "documentation":"The coverage of the control, if deployed. Scope is an enumerated type, with value Regional, or Global. A control with Global scope is effective in all Amazon Web Services Regions, regardless of the Region from which it is enabled, or to which it is deployed. A control implemented by an SCP is usually Global in scope. A control with Regional scope has operations that are restricted specifically to the Region from which it is enabled and to which it is deployed. Controls implemented by Config rules and CloudFormation hooks usually are Regional in scope. Security Hub controls usually are Regional in scope.
Regions in which the control is available to be deployed.
" } }, "documentation":"Returns information about the control, including the scope of the control, if enabled, and the Regions in which the control currently is available for deployment. For more information about scope, see Global services.
If you are applying controls through an Amazon Web Services Control Tower landing zone environment, remember that the values returned in the RegionConfiguration API operation are not related to the governed Regions in your landing zone. For example, if you are governing Regions A,B,and C while the control is available in Regions A, B, C, and D, you'd see a response with DeployableRegions of A, B, C, and D for a control with REGIONAL scope, even though you may not intend to deploy the control in Region D, because you do not govern it through your landing zone.
The requested resource does not exist.
", "error":{ "httpStatusCode":404, "senderFault":true }, "exception":true }, "String":{"type":"string"}, "ThrottlingException":{ "type":"structure", "members":{ "Message":{"shape":"String"} }, "documentation":"The request was denied due to request throttling.
", "error":{ "httpStatusCode":429, "senderFault":true }, "exception":true, "retryable":{"throttling":true} }, "Timestamp":{"type":"timestamp"}, "ValidationException":{ "type":"structure", "members":{ "Message":{"shape":"String"} }, "documentation":"The request has invalid or missing parameters.
", "error":{ "httpStatusCode":400, "senderFault":true }, "exception":true } }, "documentation":"Welcome to the Amazon Web Services Control Catalog API reference. This guide is for developers who need detailed information about how to programmatically identify and filter the common controls and related metadata that are available to Amazon Web Services customers. This API reference provides descriptions, syntax, and usage examples for each of the actions and data types that are supported by Amazon Web Services Control Catalog.
Use the following links to get started with the Amazon Web Services Control Catalog API:
Actions: An alphabetical list of all Control Catalog API operations.
Data types: An alphabetical list of all Control Catalog data types.
Common parameters: Parameters that all operations can use.
Common errors: Client and server errors that all operations can return.