controls

Creates, updates, deletes, gets or lists a controls resource.

Overview

Name	controls
Type	Resource
Id	aws.controlcatalog.controls

Fields

The following fields are returned by SELECT queries:

get_control

Name	Datatype	Description
aliases	array	A list of alternative identifiers for the control. These are human-readable designators, such as SH.S3.1. Several aliases can refer to the same control across different Amazon Web Services services or compliance frameworks.
arn	string	The Amazon Resource Name (ARN) of the control. (pattern: <code>arn:(aws(?:[-a-z])?):(controlcatalog|controltower):[a-zA-Z0-9-]::control/[0-9a-zA-Z_-]+</code>)
behavior	string	A term that identifies the control's functional behavior. One of Preventive, Detective, Proactive (PREVENTIVE, PROACTIVE, DETECTIVE)
create_time	string (date-time)	A timestamp that notes the time when the control was released (start of its life) as a governance capability in Amazon Web Services.
description	string	A description of what the control does.
governed_providers	array	A list of providers whose resources are governed by this control. For example, a value of AWS indicates that the control governs Amazon Web Services resources.
governed_resources	array	A list of resource types that are governed by this control. This information helps you understand which controls can govern certain types of resources, and conversely, which resources are affected when the control is implemented. For Amazon Web Services controls, the resources are represented as CloudFormation resource types. For non-Amazon Web Services controls, the resources are represented in a provider-specific format. If GovernedResources cannot be represented by available resource types, it’s returned as an empty list.
implementation	object	Returns information about the control, as an ImplementationDetails object that shows the underlying implementation type for a control.
name	string	The display name of the control.
parameter_requirement_summary	string	A summary that indicates whether the control requires parameters, accepts optional parameters, or does not support parameters. Use this field to determine whether you need to supply parameter values when you enable the control. (REQUIRED, OPTIONAL, NONE)
parameters	array	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.
region_configuration	object	Returns information about the control, including the scope of the control, if enabled, and the Regions in which the control 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.
severity	string	An enumerated type, with the following possible values: (LOW, MEDIUM, HIGH, CRITICAL)

list_controls

Name	Datatype	Description
aliases	array	A list of alternative identifiers for the control. These are human-readable designators, such as SH.S3.1. Several aliases can refer to the same control across different Amazon Web Services services or compliance frameworks.
arn	string	The Amazon Resource Name (ARN) of the control. (pattern: <code>arn:(aws(?:[-a-z])?):(controlcatalog|controltower):[a-zA-Z0-9-]::control/[0-9a-zA-Z_-]+</code>)
behavior	string	An enumerated type, with the following possible values: (PREVENTIVE, PROACTIVE, DETECTIVE)
create_time	string (date-time)	A timestamp that notes the time when the control was released (start of its life) as a governance capability in Amazon Web Services.
description	string	A description of the control, as it may appear in the console. Describes the functionality of the control.
governed_providers	array	A list of providers whose resources are governed by this control. For example, a value of AWS indicates that the control governs Amazon Web Services resources.
governed_resources	array	A list of resource types that are governed by this control. This information helps you understand which controls can govern certain types of resources, and conversely, which resources are affected when the control is implemented. For Amazon Web Services controls, the resources are represented as CloudFormation resource types. For non-Amazon Web Services controls, the resources are represented in a provider-specific format. If GovernedResources cannot be represented by available resource types, it’s returned as an empty list.
implementation	object	An object of type ImplementationSummary that describes how the control is implemented.
name	string	The display name of the control.
parameter_requirement_summary	string	A summary that indicates whether the control requires parameters, accepts optional parameters, or does not support parameters. Use this field to determine whether you need to supply parameter values when you enable the control. (REQUIRED, OPTIONAL, NONE)
severity	string	An enumerated type, with the following possible values: (LOW, MEDIUM, HIGH, CRITICAL)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_control	select	region		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.
list_controls	select	region	nextToken, maxResults	Returns a paginated list of all available controls in the 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.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)
maxResults	integer	The maximum number of results on a page or for an API request call.
nextToken	string	The pagination token that's used to fetch the next set of results.

SELECT examples

get_control

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.

SELECT
aliases,
arn,
behavior,
create_time,
description,
governed_providers,
governed_resources,
implementation,
name,
parameter_requirement_summary,
parameters,
region_configuration,
severity
FROM aws.controlcatalog.controls
WHERE region = '{{ region }}' -- required
;

list_controls

Returns a paginated list of all available controls in the 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.

SELECT
aliases,
arn,
behavior,
create_time,
description,
governed_providers,
governed_resources,
implementation,
name,
parameter_requirement_summary,
severity
FROM aws.controlcatalog.controls
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;