Red Canary AWS Resource Discovery Tool
- 19 Nov 2024
- 6 Minutes to read
- PDF
Red Canary AWS Resource Discovery Tool
- Updated on 19 Nov 2024
- 6 Minutes to read
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
The Red Canary resource discovery tool scans your Amazon Web Services (AWS) environment (organization or account) to determine how many resources your company is using on AWS. This tool is intended to help all stakeholders understand the resources that Red Canary will monitor and protect in your AWS environment.
This page describes how to:
Create Red Canary resource discovery roles within your account or organization (and sub-accounts) via AWS CloudFormation
Run the Red Canary resource discovery tool
Delete the resource discovery user and roles
Setup
The resource discovery binary can be found in the Red Canary S3 bucket. Click here to initiate a download.
Prerequisites
Administrative rights in AWS
Red-canary-resource-discovery-role.yaml CloudFormation template
Set up a Discovery Role in the Primary Account
See Prerequisite Steps for instructions
Set up a Discovery Role in Sub Accounts (if using Organization)
See Prerequisite Steps for instructions
If you’d like to scan a different account, you can specify the profile name via the AWS_PROFILE environment variable.
Usage
Official support for this script is limited to running from AWS CloudShell using either the prebuilt binary or a locally compiled version of this code.
Prerequisite Steps:
Open AWS CloudShell and run the following command to retrieve the ARN of your logged-in account:
$ aws sts get-caller-identity{"UserId": "ABC1234:first.last@email.com","Account": "12345677898","Arn": "arn:aws:sts::12345687:assumed-role/AWSReservedSSO_Admin/first.last@email.com"}Note: You can also find the ARN in the Identity and Access Management service section of the AWS console.
Set up a Discovery Role in the Primary Account
To scan your account (or your primary account if you’re using Organization), you’ll need to create a role with resource discovery permissions in your environment. This role will be configured with a trust boundary to allow the scanning process to assume it.
From the search bar in the AWS Console, type and select CloudFormation:
Click Create Stack:
Click With new resources (standard):
From the Prerequisite section, select Template is ready.
From the Specify template section, select Upload a template file.
Click Choose file:
Select the
red-canary-resource-discovery-role.yamlyou downloaded as a prerequisite.Click Next.
For the Stack name, enter
RedCanaryResourceDiscoveryRoleName.Note: We suggest leaving it as the default
red-canary-resource-discovery-role.Enter the ManagementAccountUserRole ARN of the user account logged-in to from Step 1.
Click Next.
Click Next.
Scroll to the bottom of the Review page.
Select the agreement.
Click Submit.
Set up a Discovery Role in Sub Accounts (if using Organization)
If your company uses AWS Organizations, you’ll need to deploy a stackset to build the Red Canary Resource Discovery role in each sub-account.
From the search bar, type and then select CloudFormation.
From the navigation menu, select StackSets.
Click Create StackSet.
From the Permissions section, select Service Managed Permissions.
From the Prerequisites section, select Template is ready.
From the Specify Template section, select Upload a template file.
Click Choose file.
Select the
red-canary-resource-discovery-role.yamlyou downloaded as part of the prerequisites.
Click Next.
Enter the stack name. For the stack name, enter
RedCanaryResourceDiscoveryRoleName.Note: We suggest leaving the name as the default
red-canary-resource-discovery-role. If you changed the name in the Setup Discovery Role in the Primary Account step, you must use the same name in this step.Enter the ManagementAccountUserRole ARN of the user account logged-in to as found in Step 1.
Click Next.
In the Configure StackSet Options section, leave the selected default options.
Click Next.
From the Add stacks to stack set section, select Deploy new stacks.
From the Deployment targets section, select Deploy to organization.
From the Specify regions section, select US East (N. Virginia). Since roles are global, only one region is required.
Click Next.
Scroll to the bottom of the Review page.
Select the agreement.
Click Submit.
Running the script:
Once you’ve configured the red-canary-resource-discovery-role, upload and run the resource discovery tool binary to scan the resources in your AWS account:
From the AWS console, navigate into AWS CloudShell
Select Actions, then click Upload file.
After a successful upload, enter
chmod +x enumerate-resourcesso you can run the binary.If you want to scan the whole organization, run the binary as is:
./enumerate-resourcesIf you want to scan the whole Organization and display the CloudTrail information for the accounts, run the binary with the AWS_TRAIL flag set to true. By default, it’s set to false:
./enumerate-resources —-AWS_TRAIL=”true”If you want to scan the whole organization and exclude certain accounts, run the binary with the EXCLUDE flag with one or multiple accounts separated by a comma:
./enumerate-resources —-AWS_TRAIL=”true” —-EXCLUDE=”123456789”./enumerate-resources —-AWS_TRAIL=”true” —-EXCLUDE=”123456789, 423456789, 523456789”If you’d like to scan a different account, you can specify the profile name via the AWS_ACCOUNT_ID environment variable:
./enumerate-resources —-AWS_ACCOUNT_ID=”123456789”
The following flags can be used for each run. Any combination of flags is supported, except for simultaneously specifying a single AWS account (AWS_ACCOUNT_ID) and excluding accounts (EXCLUDE).
./enumerate-resources —-AWS_ROLE_ARN=”arn:aws:iam:123456789:role/red-canary-resource-discovery-role” —-AWS_ACCOUNT_ID=”123456789” —-AWS_REGION=”us-east-1” —-AWS_ROLE_NAME=”red-canary-resource-discovery-role” —-AWS_TRAIL=”true” —-EXCLUDE=”123456789, 5236756789,2344675689,3446756890”
The application will display the summarized output in the console and produce a CSV report in the current working directory:
$ Red Canary - AWS Resource Discovery Scan Progress: 34 / 34Scanned 2 AWS accounts.ResourceType CountStorage Buckets 10Container Hosts 35Databases 9Non-OS Disks 12Serverless Containers 25Serverless Functions 16Virtual Machines 65Container Registry Images 13Scan completed in 45 seconds$ lsaws-resource-discovery.csv$ cat aws-resource-discovery.csv...123456789,us-east-1,AWS::S3::Bucket,3123456789,us-east-1,AWS::RDS::DBInstance,0123456789,us-east-1,AWS::ECS::Cluster,1123456789,us-east-1,AWS::EKS::Cluster,2123456789,us-east-1,AWS::ECR::PublicRepository,1123456789,us-east-1,AWS::EC2::Instance,3123456789,us-east-1,AWS::ECR::Repository,0123456789,us-east-1,AWS::EFS::FileSystem,0123456789,us-east-1,AWS::DynamoDB::Table,0123456789,us-east-1,AWS::Lambda::Function,0123456789,us-east-1,AWS::EC2::Volume,3...
Existing Setup Scan Attempt
If you’ve already granted the discovery tool the necessary permissions (a resource discovery role with trust boundary) on the AWS account, it should function without additional configuration. However, if you're using AWS Organizations or lack the required account permissions this command will fail.
From your AWS CloudShell terminal: copy, paste and run the following command:
./enumerate-resources --AWS_ACCOUNT_ID=123456789
Tear Down and Clean Up Your Stackset
Once you’ve completed the resource inventory, you should remove the created role. To efficiently clean up, delete the CloudFormation stacks and StackSets:
Delete the individual stacks
Delete the stacks within the StackSet (you cannot delete the StackSet if it’s managing the stacks)
Delete the StackSet
From the search bar, type and then select Navigate to CloudFormation.
From the left navigation menu, click Stacks.
Select the Primary Account Role creation stack:
Click Delete.
Click Delete.
Repeat Steps 1-5 for the Red Canary Resource Discovery User stack.
Click Delete.
Click StackSets.
Select the Resource Discovery Roles StackSet.
Click the Actions dropdown.
Select Delete stacks from StackSet.
Enter the Organizational Unit ID for your root account.
This can be found in the organization’s service.
Select the region where the StackSet deployed.
Click Next.
On the Review page, click Submit.
Once the operation has succeeded, click StackSets.
Select the Resource Discovery Role StackSet.
Click the Actions dropdown and then click Delete StackSet.
Confirm the Delete action.
The stacks for the Resource Discovery User and the Resource Discovery Role on the primary account have now been deleted. Additionally, the Resource Discovery Roles within each sub account, as well as the StackSet that managed them, have been removed.
This can be found in the organization’s service.
Troubleshooting
The resource discovery returns all 0s in <1 second with 0 accounts scanned:
This generally indicates that AWS CloudShell doesn’t have sufficient permissions to sts:assume the role.
Check the
aws-resource-discovery.csvfile:$ cat aws-resource-discovery.csv"Unable to determine whether the given account belongs to an organization.To scan an organization, the provided credentials must have the following permissions:- organizations:ListAccounts"Navigate into AWS IAM, find the
resource-discovery-user-role, and click Trust Relationships. Verify the policy allows the calling user tosts:AssumeRole:{"Version": "2012-10-17","Statement": [{"Effect": "Allow","Principal": {"AWS":arn:aws:sts::12345687:assumed-role/AWSReservedSSO_Admin/first.last@email.com"},"Action": "sts:AssumeRole"}]}
The resource discovery returns with various errors:
In AWS IAM, navigate into the red-canary-resource-discovery-role.
Ensure that the following permissions exist in that role:
{"Version": "2012-10-17","Statement": [{"Action": ["sts:AssumeRole","organizations:ListAccounts","ec2:DescribeRegions","s3:ListBucket","s3:GetBucketLocation","s3:GetBucketNotification","s3:ListAllMyBuckets","dynamodb:ListTables","dynamodb:ListGlobalTables","ec2:DescribeVolumes","ec2:DescribeInstances","ecr:DescribeRepositories","ecr:ListImages","ecr-public:DescribeRepositores","ecr-public:DescribeImages","ecs:ListClusters","ecs:ListServices","ecs:DescribeServices","ecs:DescribeTaskDefinition","ecs:DescribeClusters","elasticfilesystem:DescribeFileSystems""eks:ListClusters","lambda:ListFunctions","rds:DescribeDBInstances","cloudformation:ListResources","cloudformation:DescribeStacks","cloudtrail:DescribeTrails"],"Resource": "*","Effect": "Allow"}]}Sometimes the binary upload gets stuck at some percentage without making progress:
X out of the upload.
Select Actions, then click Restart.
Switch to the region geographically closest to you and try again.
Running the binary results in XML header issues:
Issue the
rm enumerate-resourcescommand in CloudShell.Switch to the region geographically closest to you and try again.
Was this article helpful?
