Account discovery - AMS Accelerate Operations Plan

Account discovery

Account discovery is the stage when AMS Accelerate works with you to assess the current state of your account, evaluate that our service is a good fit for your account, and identify any major technical blockers for supporting your environment. During the Account Discovery stage, AMS Accelerate does not provide any operational services.

To assist with the analysis and discovery of an account, we ask you to run a pre-built script in the AwsAccountDiscoveryCli command line interface that generates a comprehensive picture of your account and resources, focusing on the services you are using. You can control which part of the report to share with AMS Accelerate and then AMS Accelerate starts an iterative process to remove technical blockers, if any, before moving to the Account-Level onboarding stage.

Account discovery flowchart.
Important

The AwsAccountDiscoveryCli performs read-only calls and does not transmit data to AMS Accelerate during collection. Data is stored locally on the machine that runs the commands. AMS recommends that you review the collected data with your security team to determine whether or not you can share it with AMS for further analysis. Then, work with your AMS account team to determine the process for sharing your approved data with AMS.

For the latest changes, and to know if you need to update, see the Account Discovery Changelog zip file.

Using the AwsAccountDiscoveryCli for discovery

AwsAccountDiscoveryCli is a command line interface to discover AWS resources in a given account. You can perform discovery from a variety of platforms, including AWS CloudShell, Linux, and Windows.

Prerequisites for AwsAccountDiscoveryCli

Before you can use AwsAccountDiscoveryCli, you'll also need:

  • (Recommended) Access to the AWS CloudShell with read-only permissions (for more information, see Managing AWS CloudShell access and usage with IAM policies). You’ll need the following AMS policies:

    • arn:aws:iam::aws:policy/ReadOnlyAccess

    • arn:aws:iam::aws:policy/AWSCodeArtifactReadOnlyAccess

    • arn:aws:iam::aws:policy/AWSCloudShellFullAccess

    Create and attach the following policy to the IAM entity (user, role) you are using to initiate the discovery:

    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"support:DescribeSeverityLevels", "Resource":"*" } ] }

OR

  • The latest AWS CLI configured with read-only permissions, see Configuring the AWS CLI. AMS recommends the following AWS Managed policies:

    • arn:aws:iam::aws:policy/ReadOnlyAccess

    • arn:aws:iam::aws:policy/AWSCodeArtifactReadOnlyAccess

    Create and attach the following policy to the IAM entity (user, role) you are using to initiate the discovery:

    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"support:DescribeSeverityLevels", "Resource":"*" } ] }
Important

If the account you want to discover is part of an AWS organization, in order to collect organization-level information, AwsAccountDiscoveryCli must be called from the organization's management account or by a member account that is a delegated administrator for an AWS service, otherwise the organization-level information will not be collected. To learn more about these concepts, see AWS Organizations terminology and concepts

AWS CloudShell is a browser-based shell that makes it easy to securely manage, explore, and interact with your AWS resources. AWS CloudShell is pre-authenticated with your console credentials when you log in. Common development and operations tools are pre-installed, so no local installation or configuration is required. With AWS CloudShell, you can quickly run scripts with the AWS Command Line Interface (AWS CLI), experiment with AWS service APIs using the AWS SDKs, or use a range of other tools to be productive. You can use AWS CloudShell right from your browser at no additional cost.

Note

You can use the CloudShell AWS console from any other, or the closest, AWS Region where it is available, to perform resource discovery for all other AWS Regions. For example, to perform discovery in the Singapore region, open a CloudShell in the "US West(Oregon) us-west-2" AWS Region in the AWS Console and follow the instructions given next.

To use AwsAccountDiscoveryCli with AWS CloudShell:

  1. From any page or AWS Region in the AWS Management Console, open the AWS CloudShell to run the account discovery script shown next. Ensure that you are logged into the AWS Management Console with the correct level of permissions, see Prerequisites for AwsAccountDiscoveryCli.

    Note

    Do not change the "--domain-owner 354220221581" and " --region us-west-2" parts shown; copy the script as-is.

    python3 -m venv awsdiscovery source ~/awsdiscovery/bin/activate pip install pip --upgrade aws codeartifact login --tool pip \ --repository AwsAccountDiscoveryCli \ --domain aws-account-discovery-cli \ --domain-owner 354220221581 \ --region us-west-2 pip install awsaccountdiscoverycli
  2. Verify that the installation completed successfully:

    awsdiscover --version
  3. Start the collection for the current account:

    awsdiscover
  4. Discovery takes more time on large accounts. Once finished, compress the output folder to download the report:

    tar -czvf DiscoveryReports.tar.gz /home/cloudshell-user/AwsAccountDiscoveryReports/
  5. Select Actions in the top right corner, then choose Download file.

  6. For the Individual file path, specify the following path and then choose Download.

    /home/cloudshell-user/DiscoveryReports.tar.gz

Note

We highly recommend using Discovery of an AWS account from AWS CloudShell, as previously described. Use this method only if AWS CloudShell cannot be used due to IAM permission issues.

To discover an AWS account using Linux, follow these steps:

  1. To authenticate to the AMS CodeArtifact repository and install AwsAccountDiscoveryCli on Linux, use the following script:

    python3 -m venv awsdiscovery source ~/awsdiscovery/bin/activate pip install pip -–upgrade aws codeartifact login --tool pip --repository AwsAccountDiscoveryCli \ --domain aws-account-discovery-cli --domain-owner 354220221581 --region us-west-2 pip install awsaccountdiscoverycli
  2. Verify that the installation completed successfully (by checking that a version exists):

    awsdiscover --version
  3. Start the collection for the current account:

    awsdiscover
  4. Discovery takes more time on large accounts. After it's finished, you’ll see the output location printed in the tool's output on screen.

Note

We highly recommend using Discovery of an AWS account from AWS CloudShell, as previously described. Use this method only if AWS CloudShell cannot be used due to IAM permission issues.

To discover an AWS account using Windows, follow these steps:

  1. To authenticate to the AMS CodeArtifact repository and install AwsAccountDiscoveryCli on Windows, use the following script:

    py -m venv env .\env\Scripts\activate pip install pip --upgrade $CODEARTIFACT_TOKEN = Get-CAAuthorizationToken -Domain aws-account-discovery-cli ` -DomainOwner 354220221581 ` -Region us-west-2 pip config set global.index-url https://aws:$($CODEARTIFACT_TOKEN.AuthorizationToken)@aws-account-discovery-cli-354220221581.d.codeartifact.us-west-2.amazonaws.com/pypi/AwsAccountDiscoveryCli/simple/ pip install awsaccountdiscoverycli
  2. Verify that the installation completed successfully:

    awsdiscover --version
  3. Start the collection for the current account:

    awsdiscover
  4. Discovery takes more time on large accounts. Once finished, you’ll see the output location.

This process involves creating a read-only IAM role in each account you want to discover (child accounts) from a central (hub) account.

Hub account - IAM configuration

Attach the following policy to the IAM entity (user, role) you are using to initiate the discovery:

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "sts:AssumeRole" ], "Resource": "arn:aws:iam::*:role/AwsAccountDiscoveryRole" }] }

Child account - IAM configuration

  1. Create a file: *trust_policy.json* (replace HUB_ACCOUNT_ID with the AWS account ID of your hub account):

    { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::HUB_ACCOUNT_ID:root" }, "Action": "sts:AssumeRole" }] }
  2. Configure your AWS CLI to use the child account. You’ll need the following permissions:

    iam:CreateRole iam:AttachRolePolicy
  3. Create a role called the AwsAccountDiscoveryRole in your child account with a trust to the hub account:

    aws iam create-role --role-name AwsAccountDiscoveryRole \ --assume-role-policy-document file://trust_policy.json
  4. Attach the ReadOnlyAccess policy to the role:

    aws iam attach-role-policy --role-name AwsAccountDiscoveryRole \ --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

Run Discovery from the Hub account

Open the AWS Management Console in the Hub account and open AWS CloudShell.

Configure your AWS CLI to HUB_ACCOUNT_ID

Run the following command with the desired CHILD_ACCOUNT_ID to discover

awsdiscover -a CHILD_ACCOUNT_ID
Note

After you have completed account discovery of a child account, AMS recommends deleting the AwsAccountDiscoveryRole role if you have no further use for it.

CLI reference

Use the Help menu of the tool to get the latest information about the available commands.