Well-Architected Tool

Managing Conformity integration with the AWS Well-Architected Tool.

Sync Well-Architected review

post/well-architected-tool/sync

Conformity measures the compliance of your AWS environment with the five pillars of AWS Well-Architected by running rules mapped to Framework questions against the resources in a workload.

Failed and successful checks from a Conformity Bot run can be used to better inform responses when conducting a review in the Well-Architected Tool and provide a data-driven view of your workload.

This API endpoint updates your workload review with a summary of relevant check data in the "Notes" section of each review question. For an explanation of the fields in this summary, see Understanding the Check Summary Report.

NOTES

  • Making a call to this API will overwrite any existing notes you have previously saved on a per-question basis. It does not affect the Notes saved on a review basis.

  • In order to associate resources to a workload, using tags is considered best practice.

  • Ensure the resources in your AWS account are tagged before running Conformity Bot so only the checks associated to the workload are captured.

  • The filter is optional; if you do not specify a filter then the checks generated for all the resources in the account will be returned.

Currently, only the following is supported:

  • Single-account workloads
  • The "Well-Architected" lens

Requirements

This API is only available to ADMIN users.

In order to allow Conformity to make changes to your workload review, you will need:

  • Your Organisation's external ID. This can be obtained by making an API call to Get Organisation External Id.
  • An active Conformity AWS Account ID in your organisation
  • A tag or set of tags to filter the checks related to the resources in a workload (optional). It should follow the same format as filter[filterTags] as per the Filter options for Checks table.
  • The ARN of a defined Well-Architected workload
  • An IAM role ARN with sufficient permissions for Conformity to assume. The role should be in the same AWS account as the workload.

Set up IAM role via AWS CLI

  1. Copy the following to new respective files in the same directory and replace the "YOUR_..." strings with the correct values:

    conformity-trust-relationship.json

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::717210094962:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "YOUR_ORGANISATION_EXTERNAL_ID"
            }
          }
        }
      ]
    }
    

    conformity-well-architected-policy.json

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "wellarchitected:GetAnswer",
            "wellarchitected:UpdateAnswer"
          ],
          "Resource": "YOUR_WORKLOAD_ARN"
        }
      ]
    }
    

    setup-iam-role.sh

    #!/bin/sh
    # Creates an IAM role and attached policy that provides Conformity permission to make changes to a Well-Architected workload review.
    
    policy_arn="$(aws iam create-policy --policy-name ConformityWellArchitectedReviewPolicy --policy-document file://./conformity-well-architected-policy.json --output text --query Policy.Arn)"
    if [ "${policy_arn}" ]; then
     role_arn="$(aws iam create-role --role-name ConformityWellArchitectedReviewRole --assume-role-policy-document file://./conformity-trust-relationship.json --output text --query Role.Arn)"
    fi
    if [ "${role_arn}" ]; then
     sleep 2
     aws iam attach-role-policy --policy-arn "${policy_arn}" --role-name ConformityWellArchitectedReviewRole
     echo Role ARN is: "${role_arn}"
    fi
    
  2. In a terminal, navigate to the directory where the files are kept and run sh setup-iam-role.sh

  3. Copy the Role ARN

Set up IAM role via AWS Console

  1. Create a new IAM policy to allow access to the workload and configure the following permissions
    • For Service, choose "Well-Architected Tool"
    • For Actions > Access level, select Read > "Get Answer" and Write > "UpdateAnswer"
    • For Resources, select "Specific". Under workload, click Add ARN and input the workload ARN
  2. Create a new IAM role to provide access to Conformity:
    • For Select type of trusted entity, choose "Another AWS account"
    • For Account ID, type the Conformity AWS Account: 717210094962
    • Check Require external ID. For the External ID field, paste the organisation external ID value. Do not check the Require MFA option
    • Click Next: Permissions and select the policy you created in the previous step.
  3. Copy the Role ARN

Understanding the Check Summary Report

After receiving a 200 Success response from the API, it will take a few minutes to see the changes reflected in the review.

To view the updates made to the review, navigate to Well-Architected Tool > Workloads > {YOUR_WORKLOAD_NAME} > AWS Well-Architected Framework and select any question in the review.

The "Notes" field for the question should be updated with a summary in the following format:

Here are your findings from Trend Micro Cloud One Conformity:
Total number of Successes: 253
Total number of Failures: 40
By risk level
- Extreme successes: 0, failures: 0
- Very High successes: 0, failures: 0
- High successes: 0, failures: 0
- Medium successes: 250, failures: 28
- Low successes: 3, failures: 12
  Rule Ids to Review: [IAM-049, IAM-023, IAM-017]

The total number of successes and failures map to the number of checks from the latest Conformity Bot run for the resources in the workload.

If you have disabled any rules in your Conformity account, it will not contribute to the counts.

If you have updated a risk level in a rule setting on your account, the successes and failures for that rule will reflect on the corresponding risk level in the example above.

The `Rule Ids to Review` field includes the rule IDs that produced the failed checks in your account. Instructions to remedy the failed checks can be found on the Conformity app or the Knowledge Base.

If no checks were found for your account or filterTags, you will see the same report with successes and failures count set to 0 and `Rule Ids to Review` will be empty.
SecurityApiKeyAuth
Request
Request Body schema: application/vnd.api+json
One of:
object

Object containing the required fields for sync

Responses
200

OK

403

Forbidden. This happens when the wrong role ARN is provided, the wrong workload ARN is provided, or the user is not an ADMIN for the accountId specified.

422

Unprocessed Entity. Validation error.

Request samples
application/vnd.api+json
{
  • "meta": {
    }
}
Response samples
application/json
{
  • "meta": {
    }
}