Plexavo

An open-source AWS misconfiguration scanner that reads your account with your own local AWS credentials — nothing is ever handed to anyone else. Run it yourself, the same way you'd run aws s3 ls, and get a 0-100 security score plus a plain-English report explaining exactly what's wrong, what an attacker would actually do with it, and the exact command to fix it.

Deterministic detection (pure Python/boto3, never AI) finds the misconfigurations. Claude only rewrites already-computed technical findings into a narrative a non-security founder can act on — it never decides what counts as a finding, and it's entirely optional (see Cost below).

What it checks

31 checks across 6 categories, all validated against real, live AWS accounts (not just offline logic) unless a specific, stated limitation made that impossible — see the individual docs/*-TEST-MATRIX.md files for exactly which checks are fully verified and which have a documented, structural reason they can't be (e.g. some checks can only prove their "clean" case without disabling a real security control to test the "bad" case).

Plus scoring.py (the 0-100 score) and plexavo/report/ai_narration.py (the opt-in AI layer).

Example output

Illustrative example (a public S3 bucket, an unencrypted volume, a role that's never been assumed) — this is what a scan actually surfaces, including a finding walked through --explain:

Your AWS Security Score: 74/100 (Good)

                                              Findings (3)
┏━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Check   ┃ Severity ┃ Resource                           ┃ Detail                                     ┃
┡━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ STOR-19 │ Critical │ arn:aws:s3:::taskflow-uploads-prod │ Bucket 'taskflow-uploads-prod' allows      │
│         │          │                                    │ public read via bucket policy.             │
│ ENC-29  │ Medium   │ vol-015506d04acb46ca9              │ EBS volume 'vol-015506d04acb46ca9' is not  │
│         │          │                                    │ encrypted at rest.                         │
│ USE-27  │ High     │ AWSSecurityScannerReadOnlyRole     │ Role 'AWSSecurityScannerReadOnlyRole' has  │
│         │          │                                    │ never been assumed since creation.         │
└─────────┴──────────┴────────────────────────────────────┴────────────────────────────────────────────┘

╭────────────────────────────────────────── source: template ──────────────────────────────────────────╮
│ STOR-19 — arn:aws:s3:::taskflow-uploads-prod                                                         │
│                                                                                                      │
│ IMPACT: Bucket 'taskflow-uploads-prod' doesn't have full S3 Block Public Access protection enabled.  │
│ Without this protection, a single mistake — an overly broad bucket policy, a public ACL grant,       │
│ someone copy-pasting a policy from a tutorial — immediately exposes every object to anyone on the    │
│ internet via a plain s3:GetObject call, with nothing left to catch the mistake.                      │
│                                                                                                      │
│ CONFIDENCE: Confirmed                                                                                │
│                                                                                                      │
│ NEXT STEP: Turn on Block Public Access now: aws s3api put-public-access-block --bucket               │
│ taskflow-uploads-prod --public-access-block-configuration                                            │
│ "BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"       │
│                                                                                                      │
│ FULL FIX DETAIL: Enable all four Block Public Access settings unless there's a specific, documented  │
│ reason not to:                                                                                       │
│ aws s3api put-public-access-block --bucket taskflow-uploads-prod --public-access-block-configuration │
│ "BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯

Severity, confidence, and evidence are always separate signals, never merged into one label — a low-confidence Critical and a high-confidence Medium don't read the same. This particular finding has no Evidence line because it's a directly-observed fact with nothing uncertain about it — Evidence only appears when a check has a concrete account-state fact behind it (e.g. an IAM policy scoped by a Condition block, or a CloudTrail lookup that hit its page cap on USE-26), and Confidence only drops from "Confirmed" in that same situation. --report-html/--report-pdf render this same data as a full report; see Cost for what --explain needs and what it costs.

Quick start

Everything below uses a virtual environment (venv) — a self-contained folder holding Plexavo and its dependencies, completely separate from your system Python. This is the one install path tested end to end with zero friction, so it's the one documented here for now (other methods are planned, but aren't ready to recommend yet).

1. Create the environment (once)

python -m venv plexavo-env

You only run this once, ever — not every time you want to use Plexavo. It creates a plexavo-env folder in whatever directory you're in.

2. Activate it

plexavo-env\Scripts\activate      # Windows
source plexavo-env/bin/activate   # Mac/Linux

Your prompt should now show (plexavo-env) at the start of the line — that's your confirmation it's active. You'll do this step every time you open a new terminal, but you never repeat step 1.

3. Install

pip install plexavo

Have an Anthropic API key and want AI-narrated explanations (see Cost — it's optional and costs a few cents per scan, not free)? Install with the [ai] extra instead — same package, just with the anthropic library included:

pip install "plexavo[ai]"

No key yet, or not sure? Skip it for now — the plain install is genuinely complete on its own. You can run pip install "plexavo[ai]" later in this same environment whenever you decide you want it; nothing needs reinstalling or redone.

4. Run a scan

plexavo scan --profile my-aws-profile --report-html report.html

No --profile? It uses your default profile / environment variables, same resolution order as the AWS CLI. No AI, no API key, no cost — this alone is a complete, genuinely useful scan.

Want plain-English explanations for each finding too (needs the [ai] install above):

export ANTHROPIC_API_KEY="sk-ant-..."   # your own key, your own account
plexavo scan --profile my-aws-profile --explain --report-html report.html --report-pdf report.pdf

• Drop --explain for a fast, free scan with raw technical findings only.
• Drop --report-html/--report-pdf to just see the console table.
• --explain-limit N (default 25) caps how many findings get AI narration in one run, as a safety rail against unexpectedly large real scans.
• No ANTHROPIC_API_KEY set, or a call fails for any reason (invalid key, rate limit, network issue)? The scan and report are completely unaffected — you get raw finding detail instead of narration for that finding, not an error. See Cost.

5. When you're done for now

deactivate

This just exits the environment — nothing gets deleted or uninstalled. Your prompt goes back to normal.

6. Coming back later

Skip straight to activating again — no need to repeat steps 1 or 3:

plexavo-env\Scripts\activate      # Windows
source plexavo-env/bin/activate   # Mac/Linux

plexavo is immediately available again, exactly as you left it.

From source (for contributing, or trying an unreleased change)

git clone https://github.com/plexavo/plexavo.git
cd plexavo
pip install -e .

Project structure

plexavo/
├── auth.py                    # local AWS credential resolution
├── principals.py               # enumerates IAM users/roles + their policies
├── findings.py                  # Finding data model, Severity enum
├── scoring.py                    # 0-100 score from a list of Findings
├── cli.py                         # `plexavo scan ...` entry point
├── checks/
│   ├── iam.py                       # IAM-01 to IAM-06 (privilege escalation)
│   ├── iam_hygiene.py                # IAM-07 to IAM-14 (hygiene, cross-account trust)
│   ├── network.py                     # NET-01 to NET-04
│   ├── storage.py                      # STOR-19 to STOR-21
│   ├── encryption.py                    # ENC-29 to ENC-31
│   ├── logging.py                        # LOG-22 to LOG-25
│   └── usage.py                           # USE-26, USE-27
└── report/
    ├── html_report.py               # assembles findings into HTML via Jinja2
    ├── pdf.py                        # same data, rendered to PDF via fpdf2
    ├── ai_narration.py                # opt-in Claude narration + the 10 free templates
    ├── fonts/                          # bundled DejaVu Sans (PDF) + Geist (HTML) —
    │                                     both self-hosted, zero external requests
    └── templates/report.html.j2         # the HTML report template

examples/
└── quickstart-sandbox.tf       # one cheap, deliberately-public S3 bucket —
                                  try the scanner without pointing it at
                                  real infrastructure on day one

tests/
└── test_*.py                   # one per module, no AWS calls, run anytime:
                                  python tests/test_iam_offline.py, etc.

docs/
├── *-TEST-MATRIX.md            # one per category — the actual grading
│                                  record: what's verified, how, and any
│                                  stated limitation. Start here if you
│                                  want to know how much to trust a
│                                  given check.
├── COMPARISON.md               # honest, hands-on comparison against
│                                  Prowler, ScoutSuite, and PMapper
├── TECHNICAL-EXPLAINER.md      # implementation decisions and why
└── HOW-IT-WORKS.md

Cost

Detection is free (pure Python/boto3), always, regardless of anything else in this section. AI narration only runs with --explain, and even then: 10 of the most common, narratively-generic finding types are hand-written templates with zero API cost; only genuinely account-specific findings call Claude, typically $0.01-0.02 per finding depending on answer length. A full scan with --explain on a real account is usually well under a dollar. This is your own ANTHROPIC_API_KEY, in your own Anthropic account — this project never sees your key, never embeds one of its own, and never calls the API on your behalf without you having set one. Not "free AI" — bring your own key, and a scan with it enabled costs a few cents.

Running the tests

pip install -e ".[dev]"
for f in tests/test_*.py; do python "$f"; done

Each is self-contained — fake AWS API responses, no real credentials or network calls needed. See docs/TEST-MATRIX.md for how these map to live-AWS verification.

Contributing

See CONTRIBUTING.md — in particular, the pattern for adding a new check.

Security

Found a vulnerability in the tool itself (not a misconfiguration in your own AWS account — that's the tool working correctly)? See SECURITY.md for a private reporting path.

License

AGPL-3.0 — see LICENSE. You can use, run, and modify this freely. If you run a modified version as a hosted service, you're required to publish those modifications too. This is deliberate: it's the specific protection against a well-resourced company taking this code and standing up a competing hosted product without ever contributing back.