Service Screener

An open source guidance tool for the AWS environment. Click here for sample report.

Important note: The generated report has to be hosted locally and MUST NOT be internet accessible

This version of Service Screener may not compatible with the Greater China region. Our community folks have made it work here.

🎉 NEW: Enhanced Beta Features (v2.5.0-beta)

Enable beta features with --beta 1!

Latest Beta Features:

• 🆕 AWS Cloudscape Design System UI: Modern React-based interface

  • Self-contained single HTML file (~2.7MB with embedded React and data)
  • Enhanced GuardDuty reporting with interactive charts
  • Cross-service findings aggregation with advanced filtering
  • Interactive modernization recommendations (Sankey diagrams)
  • Trusted Advisor integration with pillar-based organization
  • Framework compliance reporting with visualizations
  • Built on AWS Cloudscape Design System (designed for accessibility)
  • Mobile responsive design

• 🔧 API Buttons: Interactive API call functionality in service pages

Standard Features (Always Enabled):

• ⚡ Concurrent Mode: Parallel check execution for better performance (use --sequential to disable)
• 📊 Enhanced TA Data: Advanced Trusted Advisor data generation
• 🔍 Comprehensive Scanning: All AWS services with Well-Architected best practices

Enable beta features with: --beta 1 (legacy AdminLTE remains default for backward compatibility)

Overview

Service Screener is a tool that runs automated checks on AWS environments and provides recommendations based on AWS and community best practices.

AWS customers can use this tool on their own environments and use the recommendations to improve the Security, Reliability, Operational Excellence, Performance Efficiency and Cost Optimisation at the service level.

This tool aims to complement the AWS Well Architected Tool.

How does it work?

Service Screener uses AWS CloudShell, a free service that provides a browser-based shell to run scripts using the AWS CLI. It runs multiple describe and get API calls to determine the configuration of your environment.

How much does it cost?

Running this tool is free as it is covered under the AWS Free Tier. If you have exceeded the free tier limits, each run will cost less than $0.01.

Prerequisites

1. Please review the DISCLAIMER before proceeding.

2. You must have an existing AWS Account.

3. You must have an IAM User with sufficient read permissions. Here is a sample policy. Additionally, the IAM User must also have the following permissions:

   • AWSCloudShellFullAccess
   • cloudformation:CreateStack
   • cloudformation:DeleteStack

4. (Optional) If you need to run cross-account operations, additional permissions are required:

   • iam:SetSecurityTokenServicePreferences

Why CloudFormation Permissions Are Required

Service Screener creates a temporary, empty CloudFormation stack during each run for audit and compliance purposes. This stack:

• Contains no actual resources - It's an empty "marker" stack that incurs no cost
• Provides audit trail - Creates a record in CloudFormation history of when Service Screener was executed
• Enables compliance tracking - Allows organizations to track security assessment activities
• Supports partner integrations - Enables tracking for AWS Partner evaluations (MPE)

The stack is automatically created at the start of each run with a unique name (format: ssv2-xxxxxxxxxxxx) and is automatically deleted when the assessment completes. The stack remains visible in CloudFormation history (when viewing "Deleted" stacks) for audit purposes. This approach leverages AWS's built-in audit capabilities without requiring additional logging infrastructure.

Installing service-screener V2

1. Log in to your AWS account using the IAM User with sufficient permissions described above.
2. Launch AWS CloudShell in any region.
3. In the AWS CloudShell terminal, run this script to update python version to 3.13:

 sudo yum install python3.13 -y

4. In the same CloudShell terminal, run this script to install the dependencies:

   cd /tmp
   python3.13 -m venv .
   source bin/activate
   python3.13 -m pip install --upgrade pip
   rm -rf service-screener-v2
   git clone https://github.com/aws-samples/service-screener-v2.git
   cd service-screener-v2
   pip install -r requirements.txt
   python3.13 unzip_botocore_lambda_runtime.py
   
   # Build Cloudscape UI (required for --beta 1 mode)
   cd cloudscape-ui
   npm install
   npm run build
   cd ..
   
   alias screener='python3 $(pwd)/main.py'

   Note: AWS CloudShell comes with Node.js pre-installed. The Cloudscape UI build takes approximately 30-60 seconds.

   Important: If you skip the Cloudscape UI build step, the --beta 1 flag will still work but will only generate the legacy AdminLTE UI. To use the new Cloudscape UI features, you must complete the build step above.

Using Service Screener

When running Service Screener, you will need to specify the regions and services you would like it to run on. For the full list of services currently supported, please see "SERVICES_IDENTIFIER_MAPPING" in Config.py.

We recommend running it in all regions where you have workloads deployed in. Adjust the commands below to suit your needs then copy and paste it into CloudShell to run Service Screener.

Example 1: (Recommended) Run in the Singapore region, check all services with NEW Cloudscape UI enabled

screener --regions ap-southeast-1 --beta 1

Example 1a: Run in the Singapore region, check all services with legacy AdminLTE UI

screener --regions ap-southeast-1

Example 2: Run in the Singapore region, check only Amazon S3

screener --regions ap-southeast-1 --services s3

Example 3: Run in the Singapore & North Virginia regions, check all services

screener --regions ap-southeast-1,us-east-1

Example 4: Run in the Singapore & North Virginia regions, check RDS and IAM

screener --regions ap-southeast-1,us-east-1 --services rds,iam

Example 5: Run in the Singapore region, filter resources based on tags (e.g: Name=env Values=prod and Name=department Values=hr,coe)

screener --regions ap-southeast-1 --tags env=prod%department=hr,coe

Example 6: Run in all regions and all services

screener --regions ALL

Example 7: Run with suppression file to ignore specific findings

screener --regions us-east-1 --services s3 --suppress_file ./suppressions.json

Performance Options

Disable Custom Pages

For faster scans focused on core AWS service analysis, you can disable custom pages processing:

screener --regions ap-southeast-1 --services ec2,s3,rds --disable-custom-pages 1

This skips processing of:

• Cost Optimization Hub (COH) - AWS cost optimization recommendations
• Trusted Advisor (TA) - TA check results and pillar organization
• Findings aggregation - Cross-service findings analysis
• Modernize recommendations - Modernization pathway analysis

Performance benefits:

• Time savings: ~2-3 minutes per scan
• Faster execution: Focuses only on core service security checks
• Reduced API calls: Skips COH, TA, and aggregation APIs

Use cases:

• CI/CD pipeline integration where speed is critical
• Quick security validation checks
• Development and testing environments
• Core service analysis without additional insights

Example: Fast security scan

screener --regions us-east-1 --services ec2,iam,s3 --disable-custom-pages 1 --beta 1

Other parameters

Suppression File

To suppress specific findings, create a JSON file with the suppressions and use the --suppress-file parameter:

{
 "metadata": {
   "version": "1.0",
   "description": "Your suppression description"
 },
 "suppressions": [
   {
     "service": "s3",
     "rule": "BucketReplication"
   },
   {
     "service": "s3",
     "rule": "BucketVersioning",
     "resource_id": ["Bucket::my-bucket-name"]
   }
 ]
}

For more details, see the suppressions documentation.

Migration Evaluation ID

For AWS Partners conducting migration evaluations:

{
    "mpe": {
        "id": "aaaa-1111-cccc"
    }
}

Usage:

screener --regions ap-southeast-1 --others '{"mpe": {"id": "aaaa-1111-cccc"}}'

Well-Architected Tool Integration

To create a workload and milestone in the Well-Architected Tool:

{
    "WA": {
        "region": "ap-southeast-1",
        "reportName": "SS_Report",
        "newMileStone": 1
    }
}

Parameters:

• region: The region where the Well-Architected workload will be created
• reportName: Name of the workload (use existing name to update)
• newMileStone:
  • Set to 1 to create a new milestone each time (Recommended)
  • Set to 0 to create a milestone only if none exists

Usage:

screener --regions ap-southeast-1 --beta 1 --others '{"WA": {"region": "ap-southeast-1", "reportName": "SS_Report", "newMileStone": 1}}'

Combining Parameters

You can combine both MPE and WA parameters:

{
    "WA": {
        "region": "ap-southeast-1",
        "reportName": "SS_Report",
        "newMileStone": 1
    },
    "mpe": {
        "id": "aaaa-1111-cccc"
    }
}

Usage:

screener --regions ap-southeast-1 --others '{"WA": {"region": "ap-southeast-1", "reportName": "SS_Report", "newMileStone": 1}, "mpe": {"id": "aaaa-1111-cccc"}}'

Downloading the report

The output is generated as a ~/service-screener-v2/output.zip file. You can download the file in the CloudShell console by clicking the Download file button under the Actions menu on the top right of the CloudShell console.

Once downloaded, unzip the file and open 'index.html' in your browser. You should see a page like this.

The new Cloudscape UI (enabled with --beta 1) includes:

• GuardDuty Special Handling - Dedicated charts, settings, and grouped findings
• Cross-Service Findings - Aggregated findings across all services with advanced filtering
• Modernization Recommendations - Interactive Sankey diagrams showing modernization pathways
• Trusted Advisor Integration - TA check results with pillar-based organization

Ensure that you can see the service(s) run on listed on the left pane. You can navigate to the service(s) listed to see detailed findings on each service.

Using the report

The report provides you an easy-to-navigate dashboard of the various best-practice checks that were run.

Use the left navigation bar to explore the checks for each service. Expand each check to read the description, find out which resources were highlighted, and get recommendations on how to remediate the findings.

Besides the HTML report, you can also find two JSON files that record the findings in each AWS account's folder:

• api-raw.json: Contains the raw findings
• api-full.json: Contains the full results in JSON format

Contributing to service-screener

We encourage public contributions! Please review CONTRIBUTING for details on our code of conduct and development process.

Development Guide

A comprehensive development guide is available at Development Guide.

Contact

Please review CONTRIBUTING to raise any issues.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.