Plexavo

Open-source AWS security scanner. 33 deterministic checks, runs locally with your own credentials, and works with AI agents.

[!NOTE]
Plexavo is built around a simple idea: security tooling should tell you what is wrong, why it matters, and what to do next, without requiring a dedicated security team.

Plexavo is an open-source cloud security tool that audits AWS accounts
for real-world misconfigurations, using your own local AWS credentials
the same way aws s3 ls does, so nothing about your account ever
leaves your machine.

Each scan produces a 0-100 security score and a plain-English report:
what's wrong, what an attacker would actually do with it, and the exact
command to fix it.

[!IMPORTANT]
Detection is not AI. Plexavo's detections are pure Python/boto3;
Claude only rewrites already-found findings for readability, and
narration is fully optional. See Cost.

[!TIP]
🤖 New: talk to Plexavo through Claude Code. No CLI flags, just ask
"scan my AWS account with Plexavo" in a Claude Code session and get a
conversational security briefing. See
Using it from Claude Code.

What it checks

33 checks across 7 categories, run against real AWS accounts:

See docs/*-TEST-MATRIX.md for how each check was verified.

[!TIP]
Don't just trust the number. Plexavo keeps severity, confidence, and evidence as separate signals, so a low-confidence Critical does not read the same as a high-confidence Medium.

Permissions

Plexavo only reads. Attach the AWS managed policy SecurityAudit to a
dedicated user or role. Setup steps:
docs/automation.md.

How Plexavo works

AWS account
     ↓
Plexavo deterministic checks
     ↓
Evidence + findings
     ↓
Severity / confidence / remediation
     ↓
HTML / PDF report
     ↓
Optional AI narration

The checks alone decide what counts as a finding. AI is optional and
only helps explain results that already exist.

Installation

Every path below installs Plexavo into its own isolated environment.

macOS & Linux

curl -LsSf https://astral.sh/uv/install.sh | sh   # skip if you have uv
uv tool install plexavo

Prefer pipx? pipx install plexavo works the
same way.

Windows

uv/pipx still work, but the PATH launcher is unsigned and Windows
Smart App Control blocks it. Run Plexavo through Python instead:

Option 1, uv (recommended)

uv tool install plexavo
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
if (!(Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }
Add-Content $PROFILE 'function plexavo { & "$env:APPDATA\uv\tools\plexavo\Scripts\python.exe" -m plexavo @args }'

Open a new terminal. plexavo now works like it does on macOS/Linux,
routed through uv's signed Python instead of the blocked launcher.

Option 2, plain venv

py -m venv plexavo-venv
.\plexavo-venv\Scripts\Activate.ps1
python -m pip install plexavo
python -m plexavo

Use python -m for everything here too. The venv's own pip.exe and
plexavo.exe are unsigned as well, only python.exe is signed.

AI narration (optional)

Want each finding rewritten as a full narrative? Install "plexavo[ai]"
instead of plexavo, and set ANTHROPIC_API_KEY. See Cost.

Using Plexavo

Run it with no arguments and it walks you through everything: picking an
AWS profile, choosing HTML or PDF, then scanning and showing your score
with every finding.

plexavo             # macOS/Linux, and Windows Option 1
python -m plexavo   # Windows Option 2

The report

Reports are generated as HTML, PDF, or both. Every finding gets a free,
template-based fix by default, no key, no cost. Full AI-written
narration kicks in automatically once an ANTHROPIC_API_KEY is
detected, see Cost.

Cost

Detection and the free templates always cost nothing. Live AI only runs
with --explain, using your own ANTHROPIC_API_KEY in your own
Anthropic account.

Plexavo never sees your key and never calls the API without it. A full
scan with --explain typically costs a few cents.

[!IMPORTANT]
No hidden AI bill. If you don't provide an Anthropic API key, Plexavo does not make an AI API call.

Using it from Claude Code

Using Claude Code? Install the
plexavo-scan plugin, then just ask: "scan my AWS account for security
issues using Plexavo." It relays exactly what Plexavo found, shows
Plexavo's own fix commands word for word, and never runs one itself: you
do. It only reads your AWS profile names, never your credentials. Don't
have Plexavo installed yet? It notices, and with a click on a yes/no
choice at each step installs uv and Plexavo for you, including the Windows
Smart App Control workaround.

/plugin marketplace add plexavo/Plexavo
/plugin install plexavo-scan@plexavo

Prefer not to add a marketplace? Save
plexavo-scan/SKILL.md
to ~/.claude/skills/plexavo-scan/SKILL.md
(%USERPROFILE%\.claude\skills\plexavo-scan\SKILL.md on Windows) instead,
same skill, just without automatic updates.

Running it on a schedule

Plexavo can also run unattended from cron or a GitHub Actions workflow,
and flag a run when something regresses so you get notified without
opening a report. See docs/automation.md.

[!NOTE]
Think of a scan as a snapshot, not a finish line. Run it repeatedly to catch regressions as your infrastructure changes.

Want to help?

You don't need to understand the whole codebase to contribute.

There are several ways to help:

• Break Plexavo: find a security blind spot or confusing result
• Add a security check: extend Plexavo's AWS coverage
• Improve test coverage: add or strengthen a test
• Improve documentation: make Plexavo easier to understand
• Suggest an improvement: tell us what would make a scan more useful

[!TIP]
First contribution? Start with issues labeled
good first issue.
Not sure where to start? Open an issue or comment on an existing one.
You don't need to figure out the codebase alone.

Pick a way to contribute

You don't need to be a Plexavo expert.

Break Plexavo

Security tools should be challenged.

Run Plexavo and tell us if you find:

• a security issue Plexavo misses
• a false positive
• a misleading severity
• incorrect remediation
• confusing report output
• an AWS resource Plexavo doesn't understand
• a case where the evidence isn't clear

You don't need to write code. If you find something useful, open an issue
and explain what happened.

Report it →

Every confirmed, genuinely new finding gets fixed and shipped, and you
get a permanent credit in the Hall of Bugs. Check the
"what doesn't count" list there first, since some gaps are already
documented.

No bounty. Public credit only.

[!TIP]
The best security tool is one that gets challenged. If you find a blind spot, break it, report it, and help make the next scan better.

Contributing code

Ready to write code? CONTRIBUTING.md covers setup,
the pattern for adding a new check, and how to run the tests.

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.

Use, run, and modify it freely. If you run a modified version as a hosted
service, you're required to publish those modifications too.