Metadata-Version: 2.4
Name: plexavo
Version: 0.4.2
Summary: Open-source AWS misconfiguration scanner — runs with your own local AWS credentials, nothing sent to anyone else.
Author: Kavee
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/plexavo/Plexavo
Project-URL: Issues, https://github.com/plexavo/Plexavo/issues
Project-URL: Security, https://github.com/plexavo/Plexavo/blob/main/SECURITY.md
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Topic :: Security
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.34
Requires-Dist: python-dateutil>=2.9
Requires-Dist: rich>=13.7
Requires-Dist: jinja2>=3.1
Requires-Dist: markupsafe>=2.1
Requires-Dist: fpdf2>=2.8
Provides-Extra: ai
Requires-Dist: anthropic>=0.116; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pypdf>=4.0; extra == "dev"
Dynamic: license-file

<div align="center">

  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/plexavo-logo-dark.png">
    <img src="assets/plexavo-logo-light.png" alt="Plexavo" height="105">
  </picture>

  <p>
    <a href="https://github.com/plexavo/plexavo">
      <img src="https://img.shields.io/github/stars/plexavo/plexavo?style=for-the-badge&logo=github&label=STARS" alt="GitHub stars">
    </a>
    <a href="https://github.com/plexavo/plexavo/blob/main/LICENSE">
      <img src="https://img.shields.io/github/license/plexavo/plexavo?style=for-the-badge&label=LICENSE" alt="License">
    </a>
    <a href="https://pypi.org/project/plexavo/">
      <img src="https://img.shields.io/pypi/v/plexavo?style=for-the-badge&logo=pypi&logoColor=white&label=PYPI" alt="PyPI version">
    </a>
    <a href="https://github.com/plexavo/plexavo/actions">
      <img src="https://img.shields.io/github/actions/workflow/status/plexavo/plexavo/ci.yml?style=for-the-badge&label=BUILD" alt="Build status">
    </a>
  </p>

  <p><strong>See your cloud. Secure what matters.</strong></p>
  <p>Turn AWS configuration data into clear, actionable security intelligence.</p>

</div>

---

<div align="center">
  <img src="assets/demo.gif" alt="Plexavo interactive scan demo" width="800">
</div>

> [!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](#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](#using-it-from-claude-code).

## ✦ What it checks

**32 checks across 6 categories**, run against real AWS accounts:

| Category | What Plexavo looks for |
|---|---|
| **IAM** | Privilege escalation paths, wildcard admin, cross-account trust, root usage, dormant credentials |
| **Network** | Security groups and RDS instances exposed to the internet |
| **Storage** | Public S3 buckets via ACLs, bucket policies, or missing Block Public Access; buckets with no access logging |
| **Encryption** | Unencrypted EBS volumes, RDS instances, S3 buckets |
| **Logging** | CloudTrail coverage and encryption, GuardDuty status |
| **Usage** | Permissions granted but never used, roles nobody has assumed in 90+ days |

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.

## ⚡ Installation

Every path below installs Plexavo into its own isolated environment.

### macOS & Linux

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

Prefer [pipx](https://pipx.pypa.io/)? `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)**

```powershell
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**

```powershell
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](#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.

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

<div align="center">
  <img src="assets/screenshot-cli.png" alt="Plexavo interactive CLI" width="700">
</div>

### 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`](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.

### 🤖 Using it from Claude Code

Using [Claude Code](https://claude.com/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, and never
runs a state-changing AWS command without asking first. Don't have Plexavo
installed yet? It notices, and with your approval 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`](https://raw.githubusercontent.com/plexavo/Plexavo/main/.claude/skills/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.

## 📊 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).

<div align="center">
  <img src="assets/screenshot-report.png" alt="Plexavo HTML report" width="700">
</div>

## 💰 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.

## 🤝 Contributing

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

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the pattern used to add a
new check.

### 🧨 Break Plexavo

Think you can make Plexavo miss something, or give confusing guidance?

[**Report it →**](../../issues/new?template=break-plexavo.yml)

Every confirmed, genuinely new finding gets fixed and shipped, and you
get a permanent credit in the [Hall of Bugs](HALL_OF_BUGS.md).

**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.

## 🔐 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`](SECURITY.md) for a private reporting path.

## 📄 License

AGPL-3.0, see [`LICENSE`](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.

---

<div align="center">

**Plexavo · Open-source cloud security, built to be understood.**

<sub>Scan. Understand. Fix. Repeat.</sub>

</div>
