controls

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

Overview

Name	controls
Type	Resource
Id	aws.auditmanager.controls

Fields

The following fields are returned by SELECT queries:

list_controls

Name	Datatype	Description
control_metadata_list	array	A list of metadata that the ListControls API returns for each control.
next_token	string	The pagination token that's used to fetch the next set of results. (pattern: <code>^[A-Za-z0-9+/=]*$</code>)

get_control

Name	Datatype	Description
id	string	The unique identifier for the control. (pattern: <code>^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$</code>)
name	string	The name of the control. (pattern: <code>^[^\]*$</code>)
action_plan_instructions	string	The recommended actions to carry out if the control isn't fulfilled. (pattern: <code>^[\w\W\s\S]*$</code>)
action_plan_title	string	The title of the action plan for remediating the control. (pattern: <code>^[\w\W\s\S]*$</code>)
arn	string	The Amazon Resource Name (ARN) of the control. (pattern: <code>^arn:.:auditmanager:.</code>)
control_mapping_sources	array	The data mapping sources for the control.
control_sources	string	The data source types that determine where Audit Manager collects evidence from for the control. (pattern: <code>^[a-zA-Z_0-9-\s.,]+$</code>)
created_at	string (date-time)	The time when the control was created.
created_by	string	The user or role that created the control. (pattern: <code>^[a-zA-Z0-9\s-_()&#91;&#93;]+$</code>)
description	string	The description of the control. (pattern: <code>^[\w\W\s\S]*$</code>)
last_updated_at	string (date-time)	The time when the control was most recently updated.
last_updated_by	string	The user or role that most recently updated the control. (pattern: <code>^[a-zA-Z0-9\s-_()&#91;&#93;]+$</code>)
state	string	The state of the control. The END_OF_SUPPORT state is applicable to standard controls only. This state indicates that the standard control can still be used to collect evidence, but Audit Manager is no longer updating or maintaining that control. (ACTIVE, END_OF_SUPPORT)
tags	object	The tags associated with the control.
testing_information	string	The steps that you should follow to determine if the control has been satisfied. (pattern: <code>^[\w\W\s\S]*$</code>)
type_	string	Specifies whether the control is a standard control or a custom control. (Standard, Custom, Core)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_controls	select	controlType, region	nextToken, maxResults, controlCatalogId	Returns a list of controls from Audit Manager.
get_control	select	control_id, region		Gets information about a specified control.
create_control	insert	region, name, controlMappingSources		Creates a new custom control in Audit Manager.
update_control	update	control_id, region, name, controlMappingSources		Updates a custom control in Audit Manager.
update_assessment_control	update	assessment_id, control_set_id, control_id, region		Updates a control within an assessment in Audit Manager.
delete_control	delete	control_id, region		Deletes a custom control in Audit Manager. When you invoke this operation, the custom control is deleted from any frameworks or assessments that it’s currently part of. As a result, Audit Manager will stop collecting evidence for that custom control in all of your assessments. This includes assessments that you previously created before you deleted the custom control.

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
assessment_id	string	The unique identifier for the assessment.
controlType	string	A filter that narrows the list of controls to a specific type.
control_id	string	The unique identifier for the control.
control_set_id	string	The unique identifier for the control set.
region	string	AWS region (default: us-east-1)
controlCatalogId	string	A filter that narrows the list of controls to a specific resource from the Amazon Web Services 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 . 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.
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

list_controls

Returns a list of controls from Audit Manager.

SELECT
control_metadata_list,
next_token
FROM aws.auditmanager.controls
WHERE controlType = '{{ controlType }}' -- required
AND region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND controlCatalogId = '{{ controlCatalogId }}'
;

get_control

Gets information about a specified control.

SELECT
id,
name,
action_plan_instructions,
action_plan_title,
arn,
control_mapping_sources,
control_sources,
created_at,
created_by,
description,
last_updated_at,
last_updated_by,
state,
tags,
testing_information,
type_
FROM aws.auditmanager.controls
WHERE control_id = '{{ control_id }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples

create_control

Creates a new custom control in Audit Manager.

INSERT INTO aws.auditmanager.controls (
name,
description,
testingInformation,
actionPlanTitle,
actionPlanInstructions,
controlMappingSources,
tags,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ description }}',
'{{ testingInformation }}',
'{{ actionPlanTitle }}',
'{{ actionPlanInstructions }}',
'{{ controlMappingSources }}' /* required */,
'{{ tags }}',
'{{ region }}'
RETURNING
control
;

Manifest

# Description fields are for documentation purposes
- name: controls
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the controls resource.
  - name: name
    value: "{{ name }}"
  - name: description
    value: "{{ description }}"
  - name: testingInformation
    value: "{{ testingInformation }}"
  - name: actionPlanTitle
    value: "{{ actionPlanTitle }}"
  - name: actionPlanInstructions
    value: "{{ actionPlanInstructions }}"
  - name: controlMappingSources
    value:
      - sourceName: "{{ sourceName }}"
        sourceDescription: "{{ sourceDescription }}"
        sourceSetUpOption: "{{ sourceSetUpOption }}"
        sourceType: "{{ sourceType }}"
        sourceKeyword:
          keywordInputType: "{{ keywordInputType }}"
          keywordValue: "{{ keywordValue }}"
        sourceFrequency: "{{ sourceFrequency }}"
        troubleshootingText: "{{ troubleshootingText }}"
  - name: tags
    value: "{{ tags }}"

UPDATE examples

update_control

Updates a custom control in Audit Manager.

UPDATE aws.auditmanager.controls
SET 
name = '{{ name }}',
description = '{{ description }}',
testingInformation = '{{ testingInformation }}',
actionPlanTitle = '{{ actionPlanTitle }}',
actionPlanInstructions = '{{ actionPlanInstructions }}',
controlMappingSources = '{{ controlMappingSources }}'
WHERE 
control_id = '{{ control_id }}' --required
AND region = '{{ region }}' --required
AND name = '{{ name }}' --required
AND controlMappingSources = '{{ controlMappingSources }}' --required
RETURNING
control;

update_assessment_control

Updates a control within an assessment in Audit Manager.

UPDATE aws.auditmanager.controls
SET 
controlStatus = '{{ controlStatus }}',
commentBody = '{{ commentBody }}'
WHERE 
assessment_id = '{{ assessment_id }}' --required
AND control_set_id = '{{ control_set_id }}' --required
AND control_id = '{{ control_id }}' --required
AND region = '{{ region }}' --required
RETURNING
control;

DELETE examples

delete_control

Deletes a custom control in Audit Manager. When you invoke this operation, the custom control is deleted from any frameworks or assessments that it’s currently part of. As a result, Audit Manager will stop collecting evidence for that custom control in all of your assessments. This includes assessments that you previously created before you deleted the custom control.

DELETE FROM aws.auditmanager.controls
WHERE control_id = '{{ control_id }}' --required
AND region = '{{ region }}' --required
;