aws-audit-scanner
aws-audit-scanner
Finds the common cost and security problems in an AWS account: forgotten spend, and the defaults that actually cause incidents. Read-only, runs locally, covers every region. Usable as a library, a CLI, or an MCP server your agent can drive.
It answers the questions you'd check by hand if you had the afternoon: is anything public that shouldn't be, does root have MFA, which access keys have never been used, what's still billing that nobody is using.
It cannot change anything. Every call it makes is a Describe*, List* or
Get*. There is no code path that creates, modifies or deletes an AWS resource,
and no dependency that could add one — see Read-only by construction.
Point it at your own account with your own credentials. Nothing is sent anywhere, and nothing is stored.
What it checks
Tool | Finds |
| Stopped instances still billing for their EBS volumes |
| Volumes attached to nothing, billed at full rate |
| Buckets exposed by ACL or policy, and buckets missing Block Public Access |
| Sensitive ports open to |
| Root access keys, root without MFA, users without MFA, keys never used or unused for 90+ days |
| Whether anything is actually being logged, and whether it covers all regions |
| Forgotten EC2/EBS/RDS resources in regions you've stopped thinking about |
Every tool returns structured findings — severity, the specific resource id, why it matters, and the console and CLI steps to fix it — so the output is usable by a program, not just readable by a person.
Related MCP server: cloud-audit
Install
npm install
npm run buildRequires Node 22+.
Use it as an MCP server
Add it to any MCP client. For Claude Desktop, in
claude_desktop_config.json:
{
"mcpServers": {
"aws-audit": {
"command": "node",
"args": ["/absolute/path/to/aws-audit-scanner/dist/index.js"],
"env": { "AWS_PROFILE": "your-profile" }
}
}
}Then ask your agent to audit the account. It calls the tools it needs and reasons across the results.
Use it as a library
import { scanIam } from 'aws-audit-scanner/dist/tools/scan-iam.js';
const result = await scanIam({ region: 'eu-west-1' });
if (result.ok) {
for (const finding of result.findings) {
console.log(`[${finding.severity}] ${finding.title}`);
}
}Every tool returns a Result-shaped value ({ ok: true, findings } or
{ ok: false, error }) rather than throwing, because a single denied permission
should degrade one check rather than fail the whole audit.
Credentials
The tools use the ambient AWS credential chain — profile, environment, instance role, whatever the SDK resolves. Nothing is read from a config file of ours and nothing is stored.
To audit a different account, assumeAuditRole wraps STS with an external ID:
import { assumeAuditRole } from 'aws-audit-scanner/dist/assume-role.js';
const assumed = await assumeAuditRole({
roleArn: 'arn:aws:iam::111122223333:role/YourAuditRole',
externalId: 'the-id-the-role-requires',
region: 'eu-west-1',
});
if (assumed.ok) await scanIam({ region: 'eu-west-1', credentials: assumed.credentials });Sessions are short-lived by design.
Read-only by construction
A promise in a README is worth very little, so this is enforced in three places:
The code. Only
Describe*,List*andGet*commands are imported from the AWS SDK. Grep for it — there is noCreate,Put,Delete,Update,Terminate,Stop,Start,Modify,AttachorDetachcommand in the source.The IAM policy. The role the hosted service asks customers to deploy is published in full at whatsinmycloud/readonly-role — the literal file, not a summary.
PERMISSIONS.mdin this repo explains why each permission is needed.The trust policy. That role can only be assumed by one named role, in one named account, gated by a server-issued external ID. It is not assumable by anyone who merely learns its ARN.
If you're evaluating whether to point this at an account you care about: read
src/tools/. Each file is short, and the scan logic is the whole story.
Coverage, honestly
Pagination is handled. Every list call follows its continuation token. Worth stating because it wasn't always true here: IAM's
ListUsersdefaultsMaxItemsto 100 when you omit it, and the docs warn it may return fewer even when more exist — so the count is never an end-of-list signal. An unpaginated scan of a 150-user account reported two users without an MFA device with complete confidence, while never looking at the other 50. A wrong number in a security report is worse than a missing one, because nothing signals that it's wrong. The EC2 calls are paginated defensively rather than because a bug was demonstrated —DescribeSecurityGroupsdocuments that omittingMaxResultsreturns everything.src/paginate.tshas the mechanics, andsrc/tools/ugly-account.test.tsfails the build if a first-page-only regression ever creeps back in. The paginator fails closed: if a continuation token repeats, or a response says it is truncated but carries no marker, it throws rather than returning what it has. Each scan turns that into an explicit failure for that check, so a partial list can never be mistaken for a complete one.Region discovery is a presence probe.
discover.tschecks every enabled region cheaply and deep-scans the ones with resources.region-sweep.tsdeliberately reads only the first page — it answers "is there anything here?", not "what exactly is here?".Costs are estimates. EBS pricing is approximated from volume type and size. Treat the figures as an order of magnitude for prioritising, not a bill.
Not covered yet: Lambda, ElastiCache, NAT Gateways, unattached Elastic IPs, old snapshots. All are real sources of forgotten spend; none are implemented.
Development
npm test # unit tests, no AWS calls — the SDK is mocked
npm run typecheck
npm run buildTests use aws-sdk-client-mock,
so the suite runs offline and never touches an account. New checks want a test
covering the interesting shape, not just the happy path — the bugs worth having
tests for here have all been about accounts that were bigger or messier than the
one the author was looking at.
Contributing
Issues and pull requests welcome. A new scan tool needs: a ScanResult-returning
function in src/tools/, a registration in src/index.ts, and tests. Keep the
read-only guarantee absolute — a pull request that introduces a mutating AWS
call will be declined regardless of how useful it is.
Who uses it
WhatsInMyCloud runs this scanner and adds prioritised plain-English reports and weekly monitoring on top. That layer is not open source; everything that touches an AWS account is in this repo.
If you'd rather not run anything yourself, that's the hosted version. If you'd rather read the code and run it locally, that's this.
Licence
MIT — see LICENSE.
Available Tools
7 toolsscan_cloudtrailB
Check if CloudTrail logging is enabled and covering all regions.
Inputs: region (required).
scan_iamA
Find IAM issues: root access keys, missing MFA, stale access keys.
Inputs: region (required).
scan_s3_public_accessA
Find S3 buckets that are publicly accessible or missing guardrails.
Inputs: region (required).
scan_security_groupsB
Find security groups with dangerous ports open to the internet.
Inputs: region (required).
scan_stopped_ec2B
Find stopped EC2 instances still incurring EBS costs.
Inputs: region (required).
scan_unattached_ebsA
Find EBS volumes not attached to any instance.
Inputs: region (required).
sweep_other_regionsC
Presence-check every other enabled region for forgotten EC2/EBS/RDS resources.
Inputs: region (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct AWS resource or audit concern (EC2, EBS, S3, security groups, IAM, CloudTrail, region sweep), with no overlapping purposes. The descriptions are specific enough to guide an agent to the correct tool without confusion.
All tools follow a consistent 'scan_<resource>' or 'sweep_<scope>' pattern, with scan_ used for the six core checks and sweep_ for cross-region discovery. This is a predictable and uniform convention that makes the tool set easy to navigate.
With 7 tools, the set is well-scoped for an AWS audit scanner, covering the major cost and security risk areas without overwhelming the user. Each tool corresponds to a distinct audit category, and the count is within the ideal range for a focused server.
The surface covers key AWS cost and security risks (stopped EC2, unattached EBS, S3 public access, security group exposure, IAM hygiene, CloudTrail coverage, and forgotten resources in other regions). Minor gaps include lack of checks for RDS snapshots or Lambda misconfigurations, but the core audit scope is well covered.
Maintenance
Related MCP Connectors
Lowers your AWS bill by helping you clean up and optimize your setup
Read-only AWS cost and security findings, priced in $/month, with a fix for each
AWS cloud security scanners for AI agents — S3, IAM, EC2, EKS, RDS, CloudTrail, CloudWatch Logs
IaC attack-path auditor: finds internet-to-crown-jewel chains in Terraform/CFN/K8s.
Related MCP Servers
- FlicenseDqualityDmaintenanceEnables read-only assessment of AWS environments by inventorying resources, running security and operational checks, and generating actionable reports with cost analysis. Designed for contractors with support for assume-role authentication using external IDs.10-
- AlicenseAqualityBmaintenanceOpen-source AWS security scanner with Attack Chains, Breach Cost Estimation, and MCP Server. 47 checks across 15 AWS services. Every finding includes copy-paste remediation (CLI + Terraform) and a dollar-risk estimate with verified source. First free standalone AWS security MCP server - Prowler and Wiz require paid SaaS.7152 PyPI75MIT
- FlicenseNot gradedqualityDmaintenanceScans AWS Security Groups for dangerous public exposures (SSH, RDP, databases) and generates risk reports.-
- AlicenseAqualityBmaintenanceEnables AI agents to run read-only AWS security audits and receive normalized, severity-ranked findings about account posture, such as stale access keys, missing MFA, public buckets, open security groups, and CloudTrail coverage.1125 PyPIMIT