update controlcatalog cli example docs

awscli/examples/controlcatalog/get-control.rst

@@ -0,0 +1,35 @@
+**To show information about an individual control**
+
+The following ``get-control`` example shows information about an individual control. ::
+
+    aws controlcatalog get-control \
+        --control-arn arn:aws:controlcatalog:::control/cwlixshc8c8mw9qiwdw2z0zav \
+        --region us-east-1
+
+Output::
+
+    {
+        "Arn": "arn:aws:controlcatalog:::control/cwlixshc8c8mw9qiwdw2z0zav",
+        "Aliases": [
+            "AWS-GR_REGION_DENY"
+        ],
+        "Name": "Deny access to AWS based on the requested AWS Region for the landing zone",
+        "Description": "Disallows access to unlisted operations in global and regional services outside of the specified Regions for the landing zone.",
+        "Behavior": "PREVENTIVE",
+        "Severity": "MEDIUM",
+        "RegionConfiguration": {
+            "Scope": "GLOBAL"
+        },
+        "Implementation": {
+            "Type": "AWS::Organizations::Policy::SERVICE_CONTROL_POLICY"
+        },
+        "ParameterRequirementSummary": "NONE",
+        "Parameters": [],
+        "CreateTime": "2022-07-25T19:00:00-05:00",
+        "GovernedResources": [],
+        "GovernedProviders": [
+            "AWS"
+        ]
+    }
+
+For more information, see `The AWS Control Tower Control Catalog <https://docs.aws.amazon.com/controltower/latest/controlreference/controls-reference.html>`__ in the *AWS Control Tower User Guide*.

awscli/examples/controlcatalog/list-common-controls.rst

@@ -0,0 +1,92 @@
+**Example 1: To display all common controls from the AWS Control Catalog**
+
+The following ``list-common-controls`` example displays all common controls from the AWS Control Catalog. ::
+
+    aws controlcatalog list-common-controls
+
+Output::
+
+    {
+        "CommonControls": [
+            {
+                "Arn": "arn:aws:controlcatalog:::common-control/d4s7ik8fgv8082v3x31hifzcc",
+                "Name": "Asset inventory reconciliation and audit",
+                "Description": "Reconcile the organization's asset inventory with other data sources, and conduct asset audits to verify the accuracy of the asset inventory.",
+                "Domain": {
+                    "Arn": "arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq",
+                    "Name": "Asset management"
+                },
+                "Objective": {
+                    "Arn": "arn:aws:controlcatalog:::objective/ad11p1961s8erra9m185wa1nn",
+                    "Name": "Asset inventory management"
+                },
+                "CreateTime": "2024-03-12T19:00:00-05:00",
+                "LastUpdateTime": "2024-03-12T19:00:00-05:00"
+            },
+            {
+                "Arn": "arn:aws:controlcatalog:::common-control/7encqm6cfsw704eoahh3ujr7y",
+                "Name": "Asset valuation",
+                "Description": "Assign a value to assets based on their cost, replacement value, or other relevant factors.",
+                "Domain": {
+                    "Arn": "arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq",
+                    "Name": "Asset management"
+                },
+                "Objective": {
+                    "Arn": "arn:aws:controlcatalog:::objective/90gifwthorhxhxq7m0rtss98u",
+                    "Name": "Asset classification"
+                },
+                "CreateTime": "2024-03-12T19:00:00-05:00",
+                "LastUpdateTime": "2024-03-12T19:00:00-05:00"
+            },
+            ...
+        ]
+    }
+
+For more information, see `About common controls <https://docs.aws.amazon.com/controltower/latest/controlreference/common-controls-list.html>`__ in the *AWS Control Tower User Guide*.
+
+**Example 2: To display common controls that have a specific objective**
+
+The following ``list-common-controls`` example displays common controls that have a specific objective. ::
+
+    aws controlcatalog list-common-controls \
+        --common-control-filter '{"Objectives": [{"Arn": "arn:aws:controlcatalog:::objective/ad11p1961s8erra9m185wa1nn"}]}'
+
+Output::
+
+    {
+        "CommonControls": [
+            {
+                "Arn": "arn:aws:controlcatalog:::common-control/d4s7ik8fgv8082v3x31hifzcc",
+                "Name": "Asset inventory reconciliation and audit",
+                "Description": "Reconcile the organization's asset inventory with other data sources, and conduct asset audits to verify the accuracy of the asset inventory.",
+                "Domain": {
+                    "Arn": "arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq",
+                    "Name": "Asset management"
+                },
+                "Objective": {
+                    "Arn": "arn:aws:controlcatalog:::objective/ad11p1961s8erra9m185wa1nn",
+                    "Name": "Asset inventory management"
+                },
+                "CreateTime": "2024-03-12T19:00:00-05:00",
+                "LastUpdateTime": "2024-03-12T19:00:00-05:00"
+            },
+            {
+                "Arn": "arn:aws:controlcatalog:::common-control/1ukpmkewk4i92tjmhsvewi4y7",
+                "Name": "Inventory of authorized assets and automated discovery",
+                "Description": "Maintain an asset inventory of organization authorized and existing hardware, software, and media. Where possible, utilize automated tools to facilitate the discovery and ongoing tracking of such assets.",
+                "Domain": {
+                    "Arn": "arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq",
+                    "Name": "Asset management"
+                },
+                "Objective": {
+                    "Arn": "arn:aws:controlcatalog:::objective/ad11p1961s8erra9m185wa1nn",
+                    "Name": "Asset inventory management"
+                },
+                "CreateTime": "2024-03-12T19:00:00-05:00",
+                "LastUpdateTime": "2024-03-12T19:00:00-05:00"
+            },
+            ...
+        ]
+    }
+
+For more information, see `About common controls <https://docs.aws.amazon.com/controltower/latest/controlreference/common-controls-list.html>`__ in the *AWS Control Tower User Guide*.

awscli/examples/controlcatalog/list-control-mappings.rst

@@ -0,0 +1,82 @@
+**Example 1: To retrieve information of all control mapping types**
+
+The following ``list-control-mappings`` example retrieves information about all control mapping types.  ::
+
+    aws controlcatalog list-control-mappings \
+        --region us-east-1
+
+Output::
+
+    {
+        "ControlMappings": [
+            {
+                "ControlArn": "arn:aws:controlcatalog:::control/ckrg5g06x08c6pem7ee4is3k5",
+                "MappingType": "FRAMEWORK",
+                "Mapping": {
+                    "Framework": {
+                        "Name": "SSAE-18-SOC-2-Oct-2023",
+                        "Item": "CC6.1"
+                    }
+                }
+            },
+            {
+                "ControlArn": "arn:aws:controlcatalog:::control/5lwgwp498974xwygy5ge7pxfz",
+                "MappingType": "FRAMEWORK",
+                "Mapping": {
+                    "Framework": {
+                        "Name": "CIS-v8.0",
+                        "Item": "14.6"
+                    }
+                }
+            },
+            {
+                "ControlArn": "arn:aws:controlcatalog:::control/6s095tcdtgab75dd0229m5x6n",
+                "MappingType": "COMMON_CONTROL",
+                "Mapping": {
+                    "CommonControl": {
+                        "CommonControlArn": "arn:aws:controlcatalog:::common-control/c0kq7ddgbp8ivhicnlr0plch4"
+                    }
+                }
+            },
+            ...
+        ]
+    }
+
+For more information, see `ControlMapping <https://docs.aws.amazon.com/controlcatalog/latest/APIReference/API_ControlMapping.html>`__ in the *AWS Control Catalog User Guide*.
+
+**Example 2: To retrieve information of a specific control mapping type**
+
+The following ``list-control-mappings`` example retrieves information about a control mapping type. ::
+
+    aws controlcatalog list-control-mappings \
+        --filter MappingTypes=FRAMEWORK
+
+Output::
+
+    {
+        "ControlMappings": [
+            {
+                "ControlArn": "arn:aws:controlcatalog:::control/ckrg5g06x08c6pem7ee4is3k5",
+                "MappingType": "FRAMEWORK",
+                "Mapping": {
+                    "Framework": {
+                        "Name": "SSAE-18-SOC-2-Oct-2023",
+                        "Item": "CC6.1"
+                    }
+                }
+            },
+            {
+                "ControlArn": "arn:aws:controlcatalog:::control/5lwgwp498974xwygy5ge7pxfz",
+                "MappingType": "FRAMEWORK",
+                "Mapping": {
+                    "Framework": {
+                        "Name": "CIS-v8.0",
+                        "Item": "14.6"
+                    }
+                }
+            },
+            ...
+        ]
+    }
+
+For more information, see `ControlMapping <https://docs.aws.amazon.com/controlcatalog/latest/APIReference/API_ControlMapping.html>`__ in the *AWS Control Catalog User Guide*.

awscli/examples/controlcatalog/list-controls.rst

@@ -0,0 +1,93 @@
+**Example 1: To retrieve a list of available controls in the Control Catalog library**
+
+The following ``list-controls`` example retrieves a list of available controls in the Control Catalog library.  ::
+
+    aws controlcatalog list-controls \
+        --region us-east-1
+
+Output::
+
+    {
+        "Controls": [
+            {
+                "Arn": "arn:aws:controlcatalog:::control/m7a5gbdf08wg2o0en010mkng",
+                "Aliases": [
+                    "BACKUP_RECOVERY_POINT_MINIMUM_RETENTION_CHECK"
+                ],
+                "Name": "Checks if a recovery point expires no earlier than after the specified period",
+                "Description": "Checks if a recovery point expires no earlier than after the specified period. The rule is NON_COMPLIANT if the recovery point has a retention point that is less than the required retention period.",
+                "Behavior": "DETECTIVE",
+                "Severity": "MEDIUM",
+                "ParameterRequirementSummary": "OPTIONAL",
+                "Implementation": {
+                    "Type": "AWS::Config::ConfigRule",
+                    "Identifier": "BACKUP_RECOVERY_POINT_MINIMUM_RETENTION_CHECK"
+                },
+                "CreateTime": "2021-07-22T19:00:00-05:00",
+                "GovernedResources": [],
+                "GovernedProviders": [
+                    "AWS"
+                ]
+            },
+            {
+                "Arn": "arn:aws:controlcatalog:::control/4b0nsxnd47747up54ytdqesxi",
+                "Aliases": [
+                    "CT.CODEBUILD.PR.3"
+                ],
+                "Name": "Require any AWS CodeBuild project environment to have logging configured",
+                "Description": "This control checks whether AWS CodeBuild projects environment has at least one logging option enabled.",
+                "Behavior": "PROACTIVE",
+                "Severity": "MEDIUM",
+                "ParameterRequirementSummary": "NONE",
+                "Implementation": {
+                    "Type": "AWS::CloudFormation::Type::HOOK"
+                },
+                "CreateTime": "2022-11-27T18:00:00-06:00",
+                "GovernedProviders": [
+                    "AWS"
+                ]
+            },
+            ...
+        ]
+    }
+
+For more information, see `The AWS Control Tower Control Catalog <https://docs.aws.amazon.com/controltower/latest/controlreference/controls-reference.html>`__ in the *AWS Control Tower User Guide*.
+
+**Example 2: To retrieve a list available controls filtered by identifier and implementation type**
+
+The following ``list-controls`` example retrieves a list of available controls filtered by identifier and implementation type. ::
+
+    aws controlcatalog list-controls \
+        --filter "{\"Implementations\":{\"Identifiers\":[\"CODEPIPELINE_DEPLOYMENT_COUNT_CHECK\"], \"Types\":[\"AWS::Config::ConfigRule\"]}}" \
+        --region us-east-1
+
+Output::
+
+    {
+        "Controls": [
+            {
+                "Arn": "arn:aws:controlcatalog:::control/8k65jh499ji8qa5tb3it7tdi5",
+                "Aliases": [
+                    "CONFIG.CODEPIPELINE.DT.1"
+                ],
+                "Name": "Checks if the first deployment stage of AWS CodePipeline performs more than one deployment",
+                "Description": "Checks if the first deployment stage of AWS CodePipeline performs more than one deployment. Optionally checks if each of the subsequent remaining stages deploy to more than the specified number of deployments (deploymentLimit).",
+                "Behavior": "DETECTIVE",
+                "Severity": "MEDIUM",
+                "ParameterRequirementSummary": "OPTIONAL",
+                "Implementation": {
+                    "Type": "AWS::Config::ConfigRule",
+                    "Identifier": "CODEPIPELINE_DEPLOYMENT_COUNT_CHECK"
+                },
+                "CreateTime": "2018-10-31T19:00:00-05:00",
+                "GovernedResources": [
+                    "AWS::CodePipeline::Pipeline"
+                ],
+                "GovernedProviders": [
+                    "AWS"
+                ]
+            }
+        ]
+    }
+
+For more information, see `The AWS Control Tower Control Catalog <https://docs.aws.amazon.com/controltower/latest/controlreference/controls-reference.html>`__ in the *AWS Control Tower User Guide*.

awscli/examples/controlcatalog/list-domains.rst

@@ -0,0 +1,29 @@
+**To show a list of domains from the Control Catalog**
+
+The following ``list-domains` example shows a list of domains from the Control Catalog. ::
+
+    aws controlcatalog list-domains
+
+Output::
+
+{
+    "Domains": [
+        {
+            "Arn": "arn:aws:controlcatalog:::domain/d4msesd9vvmzmmuvlv06m92uq",
+            "Name": "Asset management",
+            "Description": "This control domain focuses on asset management and the systematic tracking and maintenance of physical or digital assets throughout their lifecycle, including acquisition, utilization, and disposal. This reduces risks related to accidents, malfunctions, and other issues that may cause damage to property or harm to people.",
+            "CreateTime": "2024-03-12T19:00:00-05:00",
+            "LastUpdateTime": "2024-03-12T19:00:00-05:00"
+        },
+        {
+            "Arn": "arn:aws:controlcatalog:::domain/33mjpzadrlwo1by3c1012ai5i",
+            "Name": "Business continuity and recovery",
+            "Description": "This control domain focuses on planning and preparation of procedures and resources to ensure the continued operation of critical business functions in the event of a disruption, and to facilitate the recovery of normal operations afterwards.",
+            "CreateTime": "2024-03-12T19:00:00-05:00",
+            "LastUpdateTime": "2024-03-12T19:00:00-05:00"
+        },
+        ...
+    ]
+}
+
+For more information, see `DomainSummary <https://docs.aws.amazon.com/controlcatalog/latest/APIReference/API_DomainSummary.html>`__ in the *AWS Control Catalog User Guide*.