awspt — Authorized AWS Security-Assessment Suite

awspt connects to an AWS account you own (or are explicitly authorized to test) and assesses it for vulnerabilities by orchestrating best-in-class open-source tools — Prowler, ScoutSuite, PMapper, nmap, and nuclei — then normalizing everything into one unified, deduplicated report.

It is not a tool for testing accounts you do not control. Every run is gated by a scope file and a live identity check.

⚠️ Authorized use only

Only run awspt against AWS accounts you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions. By using this software you accept the terms in DISCLAIMER.md. The intrusive active-scan layer is off by default and double-gated — see below.

What it does

Layer	Engine	What it finds	Intrusive?
Cloud misconfig (CSPM)	Prowler	CIS / best-practice failures	No
Cloud misconfig (CSPM)	ScoutSuite	Multi-service config risks	No
Attack paths	PMapper	IAM privilege-escalation paths	No
Discovery	built-in (boto3)	Public IPs, world-open SGs, public S3/RDS	No
Active scan	nmap + nuclei	Open ports + templated vulns	Yes (gated)

All findings collapse into one Finding schema with a normalized severity scale and can be exported as JSON, Markdown, single-file HTML, or AWS Security Finding Format (ASFF).

Safety model

1. Scope file (scopes/*.yaml) declares the authorized account id(s), regions, and which engines may run.
2. Before any engine runs, awspt calls sts:GetCallerIdentity and refuses if the live account is not in the scope.
3. Read-only layers run by default. Active scanning (nmap/nuclei) runs only when active_scan.enabled: true in the scope and you pass --i-have-authorization, and even then it prints the exact targets and asks for confirmation.

Install

The Python engines and awspt itself:

pip install -e ".[engines]"

nmap and nuclei are system/Go binaries. The supported reproducible path is the bundled Docker image (installs everything):

docker build -t awspt .
docker run --rm -v ~/.aws:/root/.aws -v "$PWD:/work" awspt list-engines

Recommended least-privilege for the assessment principal: attach the AWS-managed SecurityAudit and ViewOnlyAccess policies. Active scanning needs no extra AWS permissions (it probes over the network, not the API).

Usage

# See which engines are available in your environment
awspt list-engines

# Preview the plan without touching AWS
awspt scan --scope scopes/example-scope.yaml --dry-run

# Read-only assessment of an authorized account, write an HTML report
awspt scan --scope scopes/my-account.yaml --profile my-sso --format html -o report.html

# Re-render a report from a stored run
awspt report --format markdown -o report.md

# Active scan (only after enabling it in scope + this flag + confirming targets)
awspt scan --scope scopes/my-account.yaml --i-have-authorization

How it's structured

awspt/
  cli.py        Typer CLI: scan, report, list-engines
  config.py     scope YAML schema + validation
  auth.py       boto3 session (profile / assume-role / SSO) + identity
  safety.py     account-match assertion + active-scan gate
  schema.py     Finding model, severity normalization, ASFF export, dedupe
  runner.py     orchestration: read-only parallel, active serial-after-confirm
  normalize.py  cross-engine merge/dedupe/sort
  store.py      SQLite persistence (run history)
  engines/      one adapter per tool (run + parse, separable for testing)
  report/       json / markdown / html renderers

Development

pip install -e ".[dev]"
pytest

Engine parsers are unit-tested against captured fixture output, so tests run without installing the heavy engines or touching AWS.

Roadmap

• diff command to compare a run against the previous one (SQLite history is already in place).
• Multi-account / AWS Organizations sweep.
• Push normalized findings to AWS Security Hub (ASFF export already implemented).
• Optional Cartography/Neo4j graph engine for richer attack-path visualization.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Adding a new engine is a small, well-defined surface (is_available / run / parse).

License

MIT © 2026 ctrldeploy. Provided "as is", without warranty. Please read DISCLAIMER.md before use.

Acknowledgements

awspt is an orchestration layer; the heavy lifting is done by the excellent open-source projects it wraps: Prowler, ScoutSuite, PMapper, nmap, and nuclei.