Cloudiscovery helps you to analyze resources in your cloud (AWS/GCP/Azure/Alibaba/IBM) account. Now this tool only can check resources in AWS, but we are working to expand to other providers.
The tool consists of various commands to help you understand the cloud infrastructure.
Commands can generate diagrams. When modelling them, we try to follow the principle:
Graphical excellence is that which gives to the viewer the greatest number of ideas in the shortest time with the least ink in the smallest space.
The commands generate reports that can be used to further analyze resources.
1.1 To detect AWS VPC resources (more on AWS VPC):
cloudiscovery aws-vpc [--vpc-id vpc-xxxxxxx] --region-name xx-xxxx-xxx [--profile-name profile] [--diagram [yes/no]] [--filter xxx] [--verbose]
1.2 To detect AWS policy resources (more on AWS Policy):
cloudiscovery aws-policy [--profile-name profile] [--diagram [yes/no]] [--filter xxx] [--verbose]
1.3 To detect AWS IoT resources (more on AWS IoT):
cloudiscovery aws-iot [--thing-name thing-xxxx] --region-name xx-xxxx-xxx [--profile-name profile] [--diagram [yes/no]] [--filter xxx] [--verbose]
1.4 To detect all AWS resources (more on AWS All):
cloudiscovery aws-all --region-name xx-xxxx-xxx [--profile-name profile] [--services xxx,xxx] [--filter xxx] [--verbose]
1.5 To check AWS limits per resource (more on AWS Limit):
cloudiscovery aws-limit --region-name xx-xxxx-xxx [--profile-name profile] [--services xxx,xxx] [--usage 0-100] [--verbose]
1.6 To run AWS security controls (experimental feature):
cloudiscovery aws-security --region-name xx-xxxx-xxx [--profile-name profile] [--commands x] [--verbose]
cloudiscovery [aws-vpc|aws-policy|aws-iot|aws-all|aws-limit] -h
Enabling verbose mode, it is possible to debug all calls to the providers endpoints and check possible problems.
It's possible to filter resources by tags and resource type. To filter, add an option
--filter <VALUE>, where
<VALUE> can be:
Name=tags.costCenter;Value=20000- to filter resources by a tag name
costCenterand with value
Name=type;Value=aws_lambda_functionto only list lambda functions.
It's possible to pass multiple values, to be able to select a value from a set. Values are split by
: sign. If a desired value has a
: sign, wrap it in
' signs e.g.
It is possible to pass multiple filter options, just pass
-f filter_1 -f filter_2. In that case, the tool will return resources that match either of the filters
Useful CF tags:
aws:cloudformation:stack-name- Stack name
aws:cloudformation:stack-id- Stack id
aws:cloudformation:logical-id- Logical id defined in CF template
This tool has been written in Python3+ and AWS-CLI and it works on Linux, Windows and Mac OS.
Make sure the latest version of AWS-CLI is installed on your workstation, and other components needed, with Python pip already installed:
pip install -U cloudiscovery
Once a while after installation, there can be some issues related with a cache from older version being used by a newer version. In that case, it's recommended to remove directory
Make sure you have properly configured your AWS-CLI with a valid Access Key and Region:
More on credentials configuration: Configuration basics
The configured credentials must be associated to a user or role with proper permissions to do all checks. If you want to use a role with narrowed set of permissions just to perform cloud discovery, use a role from the following the CF template maintained by our team.
To further increase security, you can add a block to check
aws:MultiFactorAuthPresent condition in
AssumeRolePolicyDocument. More on using IAM roles in the configuration file.
(Optional) If you want to be able to switch between multiple AWS credentials and settings, you can configure named profiles and later pass profile name when running the tool.
Cloudiscovery provides a CLI to easily perform desired actions.
Example of a diagram (diagrams.net supported):
Following resources are checked in VPC command:
The subnets are aggregated to simplify the diagram and hide infrastructure redundancies. There can be two types of subnet aggregates:
0.0.0.0/0to Internet Gateway
If EC2 instances and ECS instances are part of an autoscaling group, those instances will be aggregated on a diagram.
More information: AWS WA, REL 2: How do you plan your network topology?
Example of a diagram:
Following resources are checked in Policy command:
Some roles can be aggregated to simplify the diagram. If a role is associated with a principal and is not attached to any named policy, will be aggregated.
More information: AWS WA, SEC 3: How do you manage permissions for people and machines?
Example of a diagram:
Following resources are checked in IoT command:
A command to list ALL AWS resources.
Example of an HTML report:
The command calls all AWS services (200+) and operations with name
The operations must be allowed to be called by permissions described in AWS Permissions.
Types of resources mostly cover Terraform types. It is possible to narrow down scope of the resources to ones related with a given service with parameter
More information: AWS WA, COST 2: How do you govern usage?
It's possible to check resources limits across various service in an account. This command implements over 60 limits checks.
Example of an HTML report:
--services value,value,value parameter, you can narrow down checks to just services that you want to check.
--threshold 0-100 option, you can customize a minimum percentage threshold to start reporting a warning.
AWS has a default quota to all services. At the first time that an account is created, AWS apply this default quota to all services.
An administrator can ask to increase the quota value of a certain service via ticket. This command helps administrators detect those issues in advance.
More information: AWS WA, REL 1 How do you manage service limits?
This features is experimental, but now you can run commands to check and analyze some security issues. The following commands are available now:
If you wish to analyze accounts in regions outside the main AWS partition (e.g. GovCloud or China), you should provide credentials (e.g. a profile) that are applicable to a given partition. It's not possible to analyze regions from multiple partitions.
To build docker container using Dockerfile
docker build -t cloudiscovery .
After build container, you must start container using follow command. The run command will mount a filesystem with your actual aws cli credentials, then you won't need configure aws cli again.
docker run \ -it \ --mount type=bind,source=$HOME/.aws/,target=/root/.aws/,readonly \ cloudiscovery \ /bin/bash
This project support English and Portuguese (Brazil) languages. To contribute with a translation, follow this steps:
python msgfmt.py -o locales/NEWFOLDER/LC_MESSAGES/messages.mo locales/NEWFOLDER/LC_MESSAGES/messages
If you have improvements or fixes, we would love to have your contributions. Please use PEP 8 code style.
When developing, it's recommended to use venv.
In order to create a venv on macOS and Linux:
python3 -m venv env
py -m venv venv OR python -v venv venv
Once installed, you need to activate the virtual environment. Activation will put specific paths for
On macOS and Linux call:
Make sure you have installed pre-commit.
Install development requirements:
pip install -U -r requirements.txt -r requirements-dev.txt
Add precommit hooks:
To run pre-commit hooks, you can issue the following command:
pre-commit run --all-files
Running cloudiscovery in development mode:
python cloudiscovery/__init__.py OPTIONS
To add new resources to check limit, please remove "assets/.cache/cache.db"
git tag $VERSION.
git push --tags, a new CircleCI build is triggered.