service-screener-v2: an open source audit of an AWS account

A self-run audit, and where it sits against the Well-Architected Tool

Service Screener is a tool for customers to evaluate their AWS service configurations based on AWS and community best practices and receive recommendations on potential improvements. In the README's own words, it runs automated checks on AWS environments and provides recommendations, and AWS customers can use it on their own environments to improve Security, Reliability, Operational Excellence, Performance Efficiency and Cost Optimisation at the service level.

Those five names are the Well-Architected pillars, and the positioning is explicit: the tool aims to complement the AWS Well Architected Tool rather than replace it. The difference in approach is the point. The Well-Architected Tool is a questionnaire, an interview and a document you write yourself. Service Screener reads the actual configuration through API calls and tells you what it found.

That distinction also determines what the recommendations are worth. A check that finds an unencrypted resource or a public bucket is evidence from your account. A check that flags a design principle is a rule applied to a description. The README describes the coverage as wide, with all AWS services checked against Well-Architected best practices, and the supported service list is in a mapping called SERVICES_IDENTIFIER_MAPPING in the Config.py file under utils, which is where you would look to see whether the service you care about is covered.

The code is Python, the licence is Apache-2.0, and the repository is under the aws-samples organisation, which is the usual home for reference implementations rather than supported products. That distinction matters for how you treat its output.

The report must not leave the machine

The README puts an important note right at the top, and it is the constraint to read before anything else: the generated report has to be hosted locally and MUST NOT be internet accessible.

The reason is visible once you know what the report contains. It is a listing of the configuration of your account, generated from a set of describe and get calls run with your credentials, and it is rendered as a static HTML file with the findings, the Trusted Advisor data and the per-service recommendations. That is a description of your infrastructure's weaknesses.

There is a sample report linked in the README, hosted on CloudFront, which is worth a look to see the shape of the output. It is a report about somebody else's account, which is exactly the arrangement the note warns against for your own.

Two practical consequences follow. First, if you keep the report, it belongs on the machine that produced it, or on internal storage with the same care you would give any other internal document. Second, the beta user interface described below is a self-contained single HTML file of roughly 2.7 megabytes with embedded React and data, which is a format you can archive, mail inside a company, or attach to a ticket, with the same caveat about where it goes.

The report also includes a disclaimer document in the docs directory that the README asks you to review before proceeding, which is a reasonable thing to do before running any configuration scanner with your own credentials.

The IAM permissions are the real requirement

The prerequisites section is where the operational reality of this tool lives.

You need an existing AWS account, and you need an IAM user with sufficient read permissions. The README links the ReadOnlyAccess managed policy as the sample, and then says the user must also have AWSCloudShellFullAccess, cloudformation:CreateStack and cloudformation:DeleteStack. If you need cross-account operations, there is one more: iam:SetSecurityTokenServicePreferences.

The CloudFormation permissions look alarming until you read why they are there, which the README explains in a section of its own. Service Screener creates a temporary, empty CloudFormation stack during each run for audit and compliance purposes. The stack contains no actual resources, it is an empty marker stack that incurs no cost, and it provides an audit trail by creating a record in CloudFormation history of when the tool was executed. It enables compliance tracking for organizations, and it supports partner integrations by allowing tracking for AWS Partner evaluations.

The stack is created automatically at the start of each run with a unique name in the format ssv2-xxxxxxxxxxxx, and it is automatically deleted when the assessment completes. The stack remains visible in CloudFormation history, when viewing deleted stacks, for audit purposes. The README describes this as leveraging AWS's built-in audit capabilities without requiring additional logging infrastructure.

So the request is not for the ability to create infrastructure. It is for the ability to leave a note saying the scan happened, and it is deleted afterwards.

Two report front ends, and a beta flag that swaps them

The tool has a legacy report and a newer one, and the flag chooses.

With --beta 1 enabled, the report uses the AWS Cloudscape Design System, a modern React based interface. It is a self-contained single HTML file of about 2.7 megabytes with embedded React and data. It adds enhanced GuardDuty reporting with interactive charts, cross-service findings aggregation with advanced filtering, interactive modernization recommendations shown as Sankey diagrams, Trusted Advisor integration organised by pillar, framework compliance reporting with visualisations, accessibility by design, and a mobile responsive layout. There are also API buttons for interactive API calls in the service pages.

Without the flag, the legacy AdminLTE interface is used, and the README says it remains the default for backward compatibility.

The always-on features are listed separately. Concurrent mode runs the checks in parallel for better performance, and --sequential disables it. Enhanced Trusted Advisor data generation is standard, as is scanning across all AWS services with Well-Architected best practices.

The two flags are therefore separate axes: --beta 1 chooses the report, --sequential chooses the execution model. A large account with many regions is the case where both matter, because concurrency is what makes a broad scan finish in a reasonable time.

Installing in CloudShell, including a Node build for the new UI

The install path is deliberately constrained to AWS CloudShell, a free browser based service that provides a shell for running scripts with the AWS CLI, and the README says to launch it in any region.

The first step is Python 3.13, which the CloudShell image does not ship by default:

   sudo yum install python3.13 -y

Then the dependencies and the clone, in a virtual environment under /tmp:

   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 scripts/unzip_botocore_lambda_runtime.py

The last command unpacks the botocore Lambda runtime.

The beta user interface needs a separate build, and the README notes that CloudShell comes with Node.js pre-installed, that the build takes about 30 to 60 seconds, and that skipping it still allows --beta 1 to run but produces only the legacy AdminLTE output:

   # Build Cloudscape UI (required for --beta 1 mode)
   cd cloudscape-ui
   npm install
   npm run build
   cd ..

   alias screener='python3 $(pwd)/main.py'

The alias is the last step and is what the running examples use, so a scan is a single word.

Static credentials, because the CloudShell proxy gives out

There is a warning in the README about running long scans, and it is the kind of warning that saves an afternoon.

CloudShell vends credentials through a local proxy, and that proxy can get overwhelmed under sustained load, which causes a scan to fail with a CredentialRetrievalError. The recommended fix is to export static credentials once before running the tool, so the rest of the scan does not depend on the proxy:

eval "$(aws configure export-credentials --format env)"

The caveat follows immediately, and it is the important part. Those exported credentials expire with your CloudShell session token, typically in one to three hours, and if a scan runs longer than that you have to re-run the command and restart the scan.

That is why the README recommends running the tool in all the regions where you have workloads deployed, and why the concurrency mode exists. A scan across many regions with many services is exactly the workload that saturates the proxy, which is why the tool runs checks in parallel by default.

The commands themselves are short. Regions and services are selected with flags, for example:

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

for a scan in one region with the new report, and:

screener --regions ap-southeast-1 --services s

for the same region restricted to Amazon S3. The full list of supported services is the SERVICES_IDENTIFIER_MAPPING in utils/Config.py, and the short flags such as s are defined there.

Cost, region coverage and what this is not

Running the tool is free as it is covered under the AWS Free Tier, and the README says that if you have exceeded the free tier limits, each run will cost less than $0.01. The cost of the scan is therefore not the issue; the cost is the API calls and the time.

Region coverage has a documented gap. This version of Service Screener may not be compatible with the Greater China region, and the README links a community project where the community members have made it work. That is worth knowing before you plan to include those regions in a scan.

The dependency list also tells you what the tool is made of: boto3 for the API calls, XlsxWriter and openpyxl for spreadsheet output, netaddr for address handling, multiprocess for the concurrent execution, simple-term-menu for the interactive selection in the terminal, feedparser for the feeds that carry best practice content, bleach for sanitising the HTML that ends up in the report, python-dateutil for timestamps, and hypothesis, which is a property based testing library and is a notable inclusion in a sample project.

The repository layout is a service per directory. There is a services/ directory holding the per-service checks, a frameworks/ directory for the best practice frameworks, usecases/ for cross-service scenarios, utils/ with the Config.py that maps service identifiers, constants.py, templates/ for the report rendering, and both adminlte/ and cloudscape-ui/ for the two report front ends. There is also a poc/ directory, a q-dev/ directory, and a docs/ directory that contains the disclaimer the README asks you to read.

It is Apache-2.0 licensed, with the licence in the LICENSE file, a NOTICE file and a licenses.txt that records the third party terms, which is the pattern you want from a scanner that pulls in other people's content.

Editorial conclusion

service-screener-v2 suits an AWS team that wants a repeatable, self-run check of a real account against service-level best practices, especially a team that wants to see the findings in a report it controls rather than in a hosted console. It does not suit you if you need a tool that can be pointed at an account from a central platform, since it is designed to be run from inside CloudShell with your own credentials, and it does not suit the Greater China region without the community fork. Check three things before you run it: that the IAM user really is read-only apart from the marker stack permissions the README lists, that the generated report stays on the machine that produced it, since the README says it must not be internet accessible, and which regions you scan, because the README recommends every region where you have workloads and a scan that outlives your credentials will fail. The last push to the repository was on 2026-10-06 and the project publishes no GitHub releases.

Frequently asked questions

Official sources

1. aws-samples/service-screener-v2 on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README