SDK for PHP 3.x

Client: Aws\ControlCatalog\ControlCatalogClient
Service ID: controlcatalog
Version: 2018-05-10

This page describes the parameters and results for the operations of the AWS Control Catalog (2018-05-10), and shows how to use the Aws\ControlCatalog\ControlCatalogClient object to call the described operations. This documentation is specific to the 2018-05-10 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

GetControl ( array $params = [] )
Returns details about a specific control, most notably a list of Amazon Web Services Regions where this control is supported.
ListCommonControls ( array $params = [] )
Returns a paginated list of common controls from the Amazon Web Services Control Catalog.
ListControls ( array $params = [] )
Returns a paginated list of all available controls in the Amazon Web Services Control Catalog library.
ListDomains ( array $params = [] )
Returns a paginated list of domains from the Amazon Web Services Control Catalog.
ListObjectives ( array $params = [] )
Returns a paginated list of objectives from the Amazon Web Services Control Catalog.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListCommonControls
ListControls
ListDomains
ListObjectives

Operations

GetControl

$result = $client->getControl([/* ... */]);
$promise = $client->getControlAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->getControl([
    'ControlArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
ControlArn
Required: Yes
Type: string

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_\\-]+$

Result Syntax

[
    'Arn' => '<string>',
    'Behavior' => 'PREVENTIVE|PROACTIVE|DETECTIVE',
    'Description' => '<string>',
    'Implementation' => [
        'Type' => '<string>',
    ],
    'Name' => '<string>',
    'Parameters' => [
        [
            'Name' => '<string>',
        ],
        // ...
    ],
    'RegionConfiguration' => [
        'DeployableRegions' => ['<string>', ...],
        'Scope' => 'GLOBAL|REGIONAL',
    ],
]

Result Details

Members
Arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the control.

Behavior
Required: Yes
Type: string

A term that identifies the control's functional behavior. One of Preventive, Detective, Proactive

Description
Required: Yes
Type: string

A description of what the control does.

Implementation
Type: ImplementationDetails structure

Returns information about the control, as an ImplementationDetails object that shows the underlying implementation type for a control.

Name
Required: Yes
Type: string

The display name of the control.

Parameters
Type: Array of ControlParameter structures

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.

RegionConfiguration
Required: Yes
Type: RegionConfiguration structure

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.

Errors

ResourceNotFoundException:

The requested resource does not exist.

AccessDeniedException:

You do not have sufficient access to perform this action.

InternalServerException:

An internal service error occurred during the processing of your request. Try again later.

ValidationException:

The request has invalid or missing parameters.

ThrottlingException:

The request was denied due to request throttling.

ListCommonControls

$result = $client->listCommonControls([/* ... */]);
$promise = $client->listCommonControlsAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->listCommonControls([
    'CommonControlFilter' => [
        'Objectives' => [
            [
                'Arn' => '<string>',
            ],
            // ...
        ],
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
CommonControlFilter
Type: CommonControlFilter structure

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.

MaxResults
Type: int

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

NextToken
Type: string

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

Result Syntax

[
    'CommonControls' => [
        [
            'Arn' => '<string>',
            'CreateTime' => <DateTime>,
            'Description' => '<string>',
            'Domain' => [
                'Arn' => '<string>',
                'Name' => '<string>',
            ],
            'LastUpdateTime' => <DateTime>,
            'Name' => '<string>',
            'Objective' => [
                'Arn' => '<string>',
                'Name' => '<string>',
            ],
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
CommonControls
Required: Yes
Type: Array of CommonControlSummary structures

The list of common controls that the ListCommonControls API returns.

NextToken
Type: string

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

Errors

AccessDeniedException:

You do not have sufficient access to perform this action.

InternalServerException:

An internal service error occurred during the processing of your request. Try again later.

ValidationException:

The request has invalid or missing parameters.

ThrottlingException:

The request was denied due to request throttling.

ListControls

$result = $client->listControls([/* ... */]);
$promise = $client->listControlsAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->listControls([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
MaxResults
Type: int

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

NextToken
Type: string

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

Result Syntax

[
    'Controls' => [
        [
            'Arn' => '<string>',
            'Description' => '<string>',
            'Name' => '<string>',
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
Controls
Required: Yes
Type: Array of ControlSummary structures

Returns a list of controls, given as structures of type controlSummary.

NextToken
Type: string

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

Errors

AccessDeniedException:

You do not have sufficient access to perform this action.

InternalServerException:

An internal service error occurred during the processing of your request. Try again later.

ValidationException:

The request has invalid or missing parameters.

ThrottlingException:

The request was denied due to request throttling.

ListDomains

$result = $client->listDomains([/* ... */]);
$promise = $client->listDomainsAsync([/* ... */]);

Returns a paginated list of domains from the Amazon Web Services Control Catalog.

Parameter Syntax

$result = $client->listDomains([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
MaxResults
Type: int

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

NextToken
Type: string

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

Result Syntax

[
    'Domains' => [
        [
            'Arn' => '<string>',
            'CreateTime' => <DateTime>,
            'Description' => '<string>',
            'LastUpdateTime' => <DateTime>,
            'Name' => '<string>',
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
Domains
Required: Yes
Type: Array of DomainSummary structures

The list of domains that the ListDomains API returns.

NextToken
Type: string

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

Errors

AccessDeniedException:

You do not have sufficient access to perform this action.

InternalServerException:

An internal service error occurred during the processing of your request. Try again later.

ValidationException:

The request has invalid or missing parameters.

ThrottlingException:

The request was denied due to request throttling.

ListObjectives

$result = $client->listObjectives([/* ... */]);
$promise = $client->listObjectivesAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->listObjectives([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ObjectiveFilter' => [
        'Domains' => [
            [
                'Arn' => '<string>',
            ],
            // ...
        ],
    ],
]);

Parameter Details

Members
MaxResults
Type: int

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

NextToken
Type: string

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

ObjectiveFilter
Type: ObjectiveFilter structure

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.

Result Syntax

[
    'NextToken' => '<string>',
    'Objectives' => [
        [
            'Arn' => '<string>',
            'CreateTime' => <DateTime>,
            'Description' => '<string>',
            'Domain' => [
                'Arn' => '<string>',
                'Name' => '<string>',
            ],
            'LastUpdateTime' => <DateTime>,
            'Name' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

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

Objectives
Required: Yes
Type: Array of ObjectiveSummary structures

The list of objectives that the ListObjectives API returns.

Errors

AccessDeniedException:

You do not have sufficient access to perform this action.

InternalServerException:

An internal service error occurred during the processing of your request. Try again later.

ValidationException:

The request has invalid or missing parameters.

ThrottlingException:

The request was denied due to request throttling.

Shapes

AccessDeniedException

Description

You do not have sufficient access to perform this action.

Members
Message
Type: string

AssociatedDomainSummary

Description

A summary of the domain that a common control or an objective belongs to.

Members
Arn
Type: string

The Amazon Resource Name (ARN) of the related domain.

Name
Type: string

The name of the related domain.

AssociatedObjectiveSummary

Description

A summary of the objective that a common control supports.

Members
Arn
Type: string

The Amazon Resource Name (ARN) of the related objective.

Name
Type: string

The name of the related objective.

CommonControlFilter

Description

An optional filter that narrows the results to a specific objective.

Members
Objectives
Type: Array of ObjectiveResourceFilter structures

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.

CommonControlSummary

Description

A summary of metadata for a common control.

Members
Arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies the common control.

CreateTime
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the common control was created.

Description
Required: Yes
Type: string

The description of the common control.

Domain
Required: Yes
Type: AssociatedDomainSummary structure

The domain that the common control belongs to.

LastUpdateTime
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the common control was most recently updated.

Name
Required: Yes
Type: string

The name of the common control.

Objective
Required: Yes
Type: AssociatedObjectiveSummary structure

The objective that the common control belongs to.

ControlParameter

Description

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"]

Members
Name
Required: Yes
Type: string

The parameter name. This name is the parameter key when you call EnableControl or UpdateEnabledControl .

ControlSummary

Description

Overview of information about a control.

Members
Arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the control.

Description
Required: Yes
Type: string

A description of the control, as it may appear in the console. Describes the functionality of the control.

Name
Required: Yes
Type: string

The display name of the control.

DomainResourceFilter

Description

The domain resource that's being used as a filter.

Members
Arn
Type: string

The Amazon Resource Name (ARN) of the domain.

DomainSummary

Description

A summary of metadata for a domain.

Members
Arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies the domain.

CreateTime
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the domain was created.

Description
Required: Yes
Type: string

The description of the domain.

LastUpdateTime
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the domain was most recently updated.

Name
Required: Yes
Type: string

The name of the domain.

ImplementationDetails

Description

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.

Members
Type
Required: Yes
Type: string

A string that describes a control's implementation type.

InternalServerException

Description

An internal service error occurred during the processing of your request. Try again later.

Members
Message
Type: string

ObjectiveFilter

Description

An optional filter that narrows the list of objectives to a specific domain.

Members
Domains
Type: Array of DomainResourceFilter structures

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.

ObjectiveResourceFilter

Description

The objective resource that's being used as a filter.

Members
Arn
Type: string

The Amazon Resource Name (ARN) of the objective.

ObjectiveSummary

Description

A summary of metadata for an objective.

Members
Arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) that identifies the objective.

CreateTime
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the objective was created.

Description
Required: Yes
Type: string

The description of the objective.

Domain
Required: Yes
Type: AssociatedDomainSummary structure

The domain that the objective belongs to.

LastUpdateTime
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time when the objective was most recently updated.

Name
Required: Yes
Type: string

The name of the objective.

RegionConfiguration

Description

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.

Members
DeployableRegions
Type: Array of strings

Regions in which the control is available to be deployed.

Scope
Required: Yes
Type: string

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.

ResourceNotFoundException

Description

The requested resource does not exist.

Members
Message
Type: string

ThrottlingException

Description

The request was denied due to request throttling.

Members
Message
Type: string

ValidationException

Description

The request has invalid or missing parameters.

Members
Message
Type: string