Misleading instcutions in Documention for Create a template from scanned resources - Create a template from scanned resources (AWS CLI)

[nishikkr]

Describe the issue

Inconsistent JSON format causes error in AWS CloudFormation Resource Scan workflow

Description

There's a discrepancy between the JSON format output by the list-resource-scan-resources command and the format required by the list-resource-scan-related-resources command. This causes confusion and errors for users following the AWS CloudFormation Resource Scan workflow.

Steps to Reproduce

1. Run the list-resource-scan-resources command:

   aws cloudformation list-resource-scan-resources \
    --resource-scan-id arn:aws:cloudformation:us-east-1:123456789012:resourceScan/0a699f15-489c-43ca-a3ef-3e6ecfa5da60 \
    --resource-identifier MyApp > resources.json

2. Use the resulting resources.json file in the list-resource-scan-related-resources command:

   aws cloudformation list-resource-scan-related-resources \
    --resource-scan-id arn:aws:cloudformation:us-east-1:123456789012:resourceScan/0a699f15-489c-43ca-a3ef-3e6ecfa5da60 \
    --resources file://resources.json

Expected Behavior

The resources.json file generated in step 1 should be directly usable in step 2 without manual modification.

Actual Behavior

Users receive a validation error:

Error parsing parameter '--resources': Invalid JSON: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
JSON received: {

Root Cause

The JSON format output by list-resource-scan-resources is incompatible with the format required by list-resource-scan-related-resources. Specifically:

1. The output includes a top-level "Resources" key, which is not expected by the input.
2. Each resource object includes a "ManagedByStack" key, which is not expected by the input.
3. The output is an object, while the input expects an array.

Current Workaround

Users must manually edit the resources.json file to:

1. Remove the outer "Resources" key
2. Remove the "ManagedByStack" key from each resource object
3. Convert the outer structure from an object to an array

Example of required JSON format:

[
    {
        "ResourceType": "AWS::EKS::Cluster",
        "ResourceIdentifier": {
            "ClusterName": "MyAppClusterName"
        }
    },
    {
        "ResourceType": "AWS::AutoScaling::AutoScalingGroup",
        "ResourceIdentifier": {
            "AutoScalingGroupName": "MyAppASGName"
        }
    }
]

Proposed Solution

Consider one or more of the following:

1. Modify list-resource-scan-resources to output JSON in the format required by list-resource-scan-related-resources.
2. Update list-resource-scan-related-resources to accept the JSON format output by list-resource-scan-resources.
3. Add a new command or flag to transform the output of list-resource-scan-resources into the required input format for list-resource-scan-related-resources.
4. Improve documentation to clearly explain the required JSON transformation between these steps.

Impact

This issue creates a confusing user experience and adds unnecessary complexity to the AWS CloudFormation Resource Scan workflow. It may lead to increased support requests and reduced adoption of this feature.

Links

Create a template from scanned resources - Create a template from scanned resources (AWS CLI) - https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/iac-generator-create-template-from-scanned-resources.html#create-template-from-scanned-resources-cli

[tim-finnigan]

Thanks for reaching out. For requests to update the documentation, we recommend using the Provide feedback links at the bottom of User Guide or API pages. In this case, the CloudFormation team owns that User Guide and the ListResourceScanResources API, so they would need to approve/implement any changes.

Requests to modify the API behavior/responses fall into a different category. If you'd us to reach out to the CloudFormation team with those requests, can you elaborate a bit on your use case and how you're blocked by the current behavior? I'm wondering if what you're trying to accomplish could be done using the --query parameter, for example:

aws cloudformation list-resource-scan-resources \
  --resource-scan-id arn:aws:cloudformation:us-east-1:123456789012:resourceScan/0a12345-489c-43ca-a3ef-3e6ecfa5da60 \
  --resource-identifier MyApp \
  --query 'Resources[].{ResourceType: ResourceType, ResourceIdentifier: ResourceIdentifier}'

Requests to change what an API returns are generally not considered due to the need to maintain backwards compatibility for those relying on the current behavior.

[github-actions[bot]]

Greetings! It looks like this issue hasn’t been active in longer than five days. We encourage you to check if this is still an issue in the latest release. In the absence of more information, we will be closing this issue soon. If you find that this is still a problem, please feel free to provide a comment or upvote with a reaction on the initial post to prevent automatic closure. If the issue is already closed, please feel free to open a new one.