Validate AWS CloudFormation templates against AWS Well-Architected Sustainability Pillar best practices.

Sustainability scanner is an open source tool that helps you create a more sustainable infrastructure on AWS. It takes in your Cloudformation template as input, evaluates it against a set of sustainability best practices and generates a report with a sustainability score and suggested improvements to apply to your template. SusScanner comes with a set of rule implementations aligned to the AWS Well-Architected Pillar for Sustainability. However, this is not an exhaustive list and new rules will come out as the tool evolves. Furthermore, you can extend these rules (located in the susscanner/rules dir) in accordance with your company-specific sustainability policies.

Sustainability Scanner in action

Scroll down to the getting started section to get detailed examples on how to use the tool.

• Installation
  • Prerequisites
  • Getting Started
    1. Install via pip
    2. Install from source
• Sustainability Score
• Rule Set
  • Disabling Rules
  • Extending the rule set
• FAQs
• Security
• License

To install Sustainability Scanner please follow the following instructions.

• AWS CloudFormation Guard
  • an open-source general-purpose policy-as-code evaluation tool which SusScanner builds on top of
• Python 3.6 or later
  • check version with python3 -V

There are two options to install the tool:

To install the project via pip, you simply have to call

pip3 install sustainability-scanner

Run susscanner --help to get a list of options and arguments for the tool. You should see an output like below:

susscanner --help
Usage: susscanner [OPTIONS] [CloudFormation Template]

Arguments:
  [CloudFormation Template]  The AWS CloudFormation template(s) to use  [required]

Options:
  --version  -v      Show the application version and exit.
  --rules    -r PATH Location for a custom rules metadata file. 
  --help             Show this message and exit.

You can scan a template by using the command:

susscanner [path/to/cloudformation/template_or_templates]

You should see an output like below;

susscanner test.yaml
{
    "title": "Sustainability Scanner Report",
    "file": "test.yaml",
    "version": "1.2.5",
    "sustainability_score": 8,
    "failed_rules": [
        {
            "rule_name": "rest_api_compression_max",
            "severity": "MEDIUM",
            "message": "Consider configuring the payload compression with MinimumCompressionSize. Compressing the payload will in general reduce the network traffic.",
            "links": [
                "https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html",
                "https://docs.aws.amazon.com/wellarchitected/latest/sustainability-pillar/sus_sus_data_a8.html"
            ],
            "resources": [
                {
                    "name": "/Resources/API-GW-2/Properties/MinimumCompressionSize",
                    "line": "15"
                }
            ]
        }
    ]
}

If you want to use your own rules_metadata file you can specify one using the -r or --rules options.

git clone https://github.com/awslabs/sustainability-scanner.git

cd sustainability-scanner

# from the root directory of the project
python3 -m venv .venv
source .venv/bin/activate

python3 -m pip install -r requirements.txt

That's it! You're ready to use Sustainability Scanner.

You can scan a template by using the command;

#from the root directory of the project
python3 -m susscanner [path/to/cloudformation/template_or_templates]

After you've scanned your AWS CloudFormation template, as part of the report, you will get a Sustainability Score. It follows inverted scoring and increases your score for each best practice you can improve; the lower the score the better. Higher severity rules have a greater scope for improvement e.g. Failing a HIGH SEV rule will increase your score more than a LOW SEV rule. If you are following all the best practices or none of the rules apply to your infrastructure this score will be 0. Find the scoring by severity in the table below

SusScanner comes with a set of best practices/rules that align with best practices for sustainability in the cloud. You can find the list of best practices, the service they apply to and their improvement actions in the rules_metadata.json file.

As mentioned before, the tool comes with a pre-defined set of rules, all of which are enabled by default. However, you can disable a rule if it is not applicable to your setup. In the susscanner directory you can find a file called rules_metadata.json. This configuration file can be used to specify which rules to include. The structure of this file is as follows:

01:{
02:    "all_rules": 
03:    {
04:        "rule_on_service_level": {
05:            "enabled": true,
06:            "rules": [
07:            {
08:                "rule_name": "name_of_the_rule",
09:                "severity": "MEDIUM",
10:                "message": "message_of_the_rule",
11:                "enabled": true,
12:                "links": [
13:                    "link_1",
14:                    "link_2"
15:                ]
16:            }
17:        }
18:    }
19:}

Rules can be enabled or disabled on both a service level and rule level. If you want to disable the checks for a service, for example Amazon Elastic Compute Cloud (EC2), you can set enabled to false on line 5 of the example above. Since a service can have multiple rules you can opt to disable rules on a per rule base. This can be done by setting enabled to false, in the example shown on line 11.

If you wish to extend the pre-existing set of rules you can define your own by adding AWS CloudFormation Guard rules to the susscanner/rules directory. For each rule that you add, don't forget to add test cases to validate it. You can validate a rule by running:

cfn-guard test --rules-file ./susscanner/rules/<RULE_FILE> --test-data ./susscanner/rules/test_cases/<TEST_FILE>

AWS CloudFormation Guard uses a domain-specific language (DSL) to define the rules. More information can be found at the AWS CloudFormation Guard documentation page. When defining a new rule there are 2 requirements to ensure compatibility with the Sustainability Scanner project.

1. Rules FAIL when the resulting state is not desirable in terms of sustainability and PASS when the outcome is sustainable.
2. Add the rule created in the susscanner/rules directory to the rules_metadata.json file. Define the name of the rule in the rule_name variable.

No, the recommendations are not mandatory to implement, if you categorize a best practice as not applicable or prefer the status quo given your workload, you can choose to either ignore the failed rule or disable it.

You will get a Sustainability Scanner Report without failed rules. This looks as follows:

{
    "title": "Sustainability Scanner Report",
    "file": "cloudformation.yaml",
    "version": "1.2.5",
    "sustainability_score": 0,
    "failed_rules": []
}

Yes, a Github Action to run the scanner is available on the marketplace.

See CONTRIBUTING for more information.

This project is licensed under the MIT-0 License.