plexavo 0.1.2__tar.gz → 0.2.0__tar.gz

{plexavo-0.1.2 → plexavo-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.1.2
+Version: 0.2.0
 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
@@ -75,7 +75,9 @@ Plus `scoring.py` (the 0-100 score) and `plexavo/report/ai_narration.py`
 
 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`:
+finding's free template remediation (shown by default, no `--explain`
+needed; `--explain` would replace this panel with a full AI narrative
+instead):
 
 ```
 Your AWS Security Score: 74/100 (Good)
@@ -125,37 +127,27 @@ scoped by a Condition block, or a CloudTrail lookup that hit its page cap on
 
 ## 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).
+**Recommended: [uv](https://docs.astral.sh/uv/).** It installs Plexavo into
+its own isolated environment automatically — no venv to create, activate,
+or remember to reactivate in every new terminal.
 
-### 1. Create the environment (once)
+### 1. Install uv (if you don't already have it)
 
 ```bash
-python -m venv plexavo-env
+curl -LsSf https://astral.sh/uv/install.sh | sh          # Mac/Linux
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
 ```
 
-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.
+(Full options: [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).)
 
-### 2. Activate it
+### 2. Install Plexavo
 
 ```bash
-plexavo-env\Scripts\activate      # Windows
-source plexavo-env/bin/activate   # Mac/Linux
+uv tool install plexavo
 ```
 
-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
-
-```bash
-pip install plexavo
-```
+That's it — `plexavo` is now on your PATH in every terminal, until you
+uninstall it. No activate step, ever.
 
 **Have an Anthropic API key and want AI-narrated explanations** (see
 [Cost](#cost) — it's optional and costs a few cents per scan, not
@@ -163,67 +155,97 @@ free)? Install with the `[ai]` extra instead — same package, just with
 the `anthropic` library included:
 
 ```bash
-pip install "plexavo[ai]"
+uv tool 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.
+genuinely complete on its own. Add it later with:
+
+```bash
+uv tool install --reinstall "plexavo[ai]"
+```
+
+Just want to try it once without installing anything?
 
-### 4. Run a scan
+```bash
+uvx plexavo scan --profile my-aws-profile
+```
+
+Updating or removing later:
+
+```bash
+uv tool upgrade plexavo
+uv tool uninstall plexavo
+```
+
+### 3. Run a scan
 
 ```bash
 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.
+same resolution order as the AWS CLI. No AI, no API key, no cost — and
+findings still come with free Next Step / Full Fix Detail guidance
+wherever a template exists (10 common check types); this alone is a
+complete, genuinely useful scan.
 
-Want plain-English explanations for each finding too (needs the
-`[ai]` install above):
+Want a full AI-written explanation for *every* finding instead (needs
+the `[ai]` install above)?
 
 ```bash
 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 `--explain` and findings still get free template remediation where
+  available (no API key needed) and raw technical detail otherwise.
+  `--explain` replaces that with a live AI narrative for every finding,
+  including the templated ones.
 - 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.
+- `--explain-limit N` (default 25) caps how many findings get a live AI
+  call when `--explain` is passed, as a safety rail against unexpectedly
+  large real scans — it doesn't limit the free template remediation.
 - 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](#cost).
+  unaffected — that finding falls back to template/raw detail instead of
+  an AI narrative, not an error. See [Cost](#cost).
+
+### Alternative: pipx
 
-### 5. When you're done for now
+Already use [pipx](https://pipx.pypa.io/)? It works exactly the same way —
+its own isolated environment, one global command, no venv:
 
 ```bash
-deactivate
+pipx install plexavo
+pipx install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
-This just exits the environment — nothing gets deleted or uninstalled.
-Your prompt goes back to normal.
-
-### 6. Coming back later
+### Alternative: pip + venv
 
-Skip straight to activating again — no need to repeat steps 1 or 3:
+Prefer to manage the environment yourself, or on a system without uv/pipx?
+Modern Python (PEP 668) blocks a plain `pip install` outside a venv on
+many systems, so create one first:
 
 ```bash
+python -m venv plexavo-env
 plexavo-env\Scripts\activate      # Windows
 source plexavo-env/bin/activate   # Mac/Linux
+
+pip install plexavo
+pip install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
-`plexavo` is immediately available again, exactly as you left it.
+You'll need to reactivate this venv (`plexavo-env\Scripts\activate` /
+`source plexavo-env/bin/activate`) every time you open a new terminal —
+`deactivate` exits it without uninstalling anything.
 
 ### From source (for contributing, or trying an unreleased change)
 
 ```bash
 git clone https://github.com/plexavo/plexavo.git
 cd plexavo
-pip install -e .
+uv pip install -e .   # or: pip install -e . (inside a venv)
 ```
 
 ## Project structure
@@ -275,10 +297,14 @@ docs/
 ## 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
+else in this section. Every scan also gets free Next Step / Full Fix
+Detail remediation wherever one of 10 hand-written templates matches the
+finding type — no flag, no API key, zero cost, on by default.
+
+Live AI only runs with `--explain`, and when it does it's used for
+*every* finding, including the 10 templated ones (a deliberate choice —
+"AI narration on" always means fully AI-written content, not a mix of
+template and AI), 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

{plexavo-0.1.2 → plexavo-0.2.0}/README.md

@@ -46,7 +46,9 @@ Plus `scoring.py` (the 0-100 score) and `plexavo/report/ai_narration.py`
 
 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`:
+finding's free template remediation (shown by default, no `--explain`
+needed; `--explain` would replace this panel with a full AI narrative
+instead):
 
 ```
 Your AWS Security Score: 74/100 (Good)
@@ -96,37 +98,27 @@ scoped by a Condition block, or a CloudTrail lookup that hit its page cap on
 
 ## 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).
+**Recommended: [uv](https://docs.astral.sh/uv/).** It installs Plexavo into
+its own isolated environment automatically — no venv to create, activate,
+or remember to reactivate in every new terminal.
 
-### 1. Create the environment (once)
+### 1. Install uv (if you don't already have it)
 
 ```bash
-python -m venv plexavo-env
+curl -LsSf https://astral.sh/uv/install.sh | sh          # Mac/Linux
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
 ```
 
-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.
+(Full options: [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).)
 
-### 2. Activate it
+### 2. Install Plexavo
 
 ```bash
-plexavo-env\Scripts\activate      # Windows
-source plexavo-env/bin/activate   # Mac/Linux
+uv tool install plexavo
 ```
 
-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
-
-```bash
-pip install plexavo
-```
+That's it — `plexavo` is now on your PATH in every terminal, until you
+uninstall it. No activate step, ever.
 
 **Have an Anthropic API key and want AI-narrated explanations** (see
 [Cost](#cost) — it's optional and costs a few cents per scan, not
@@ -134,67 +126,97 @@ free)? Install with the `[ai]` extra instead — same package, just with
 the `anthropic` library included:
 
 ```bash
-pip install "plexavo[ai]"
+uv tool 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.
+genuinely complete on its own. Add it later with:
+
+```bash
+uv tool install --reinstall "plexavo[ai]"
+```
+
+Just want to try it once without installing anything?
 
-### 4. Run a scan
+```bash
+uvx plexavo scan --profile my-aws-profile
+```
+
+Updating or removing later:
+
+```bash
+uv tool upgrade plexavo
+uv tool uninstall plexavo
+```
+
+### 3. Run a scan
 
 ```bash
 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.
+same resolution order as the AWS CLI. No AI, no API key, no cost — and
+findings still come with free Next Step / Full Fix Detail guidance
+wherever a template exists (10 common check types); this alone is a
+complete, genuinely useful scan.
 
-Want plain-English explanations for each finding too (needs the
-`[ai]` install above):
+Want a full AI-written explanation for *every* finding instead (needs
+the `[ai]` install above)?
 
 ```bash
 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 `--explain` and findings still get free template remediation where
+  available (no API key needed) and raw technical detail otherwise.
+  `--explain` replaces that with a live AI narrative for every finding,
+  including the templated ones.
 - 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.
+- `--explain-limit N` (default 25) caps how many findings get a live AI
+  call when `--explain` is passed, as a safety rail against unexpectedly
+  large real scans — it doesn't limit the free template remediation.
 - 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](#cost).
+  unaffected — that finding falls back to template/raw detail instead of
+  an AI narrative, not an error. See [Cost](#cost).
+
+### Alternative: pipx
 
-### 5. When you're done for now
+Already use [pipx](https://pipx.pypa.io/)? It works exactly the same way —
+its own isolated environment, one global command, no venv:
 
 ```bash
-deactivate
+pipx install plexavo
+pipx install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
-This just exits the environment — nothing gets deleted or uninstalled.
-Your prompt goes back to normal.
-
-### 6. Coming back later
+### Alternative: pip + venv
 
-Skip straight to activating again — no need to repeat steps 1 or 3:
+Prefer to manage the environment yourself, or on a system without uv/pipx?
+Modern Python (PEP 668) blocks a plain `pip install` outside a venv on
+many systems, so create one first:
 
 ```bash
+python -m venv plexavo-env
 plexavo-env\Scripts\activate      # Windows
 source plexavo-env/bin/activate   # Mac/Linux
+
+pip install plexavo
+pip install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
-`plexavo` is immediately available again, exactly as you left it.
+You'll need to reactivate this venv (`plexavo-env\Scripts\activate` /
+`source plexavo-env/bin/activate`) every time you open a new terminal —
+`deactivate` exits it without uninstalling anything.
 
 ### From source (for contributing, or trying an unreleased change)
 
 ```bash
 git clone https://github.com/plexavo/plexavo.git
 cd plexavo
-pip install -e .
+uv pip install -e .   # or: pip install -e . (inside a venv)
 ```
 
 ## Project structure
@@ -246,10 +268,14 @@ docs/
 ## 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
+else in this section. Every scan also gets free Next Step / Full Fix
+Detail remediation wherever one of 10 hand-written templates matches the
+finding type — no flag, no API key, zero cost, on by default.
+
+Live AI only runs with `--explain`, and when it does it's used for
+*every* finding, including the 10 templated ones (a deliberate choice —
+"AI narration on" always means fully AI-written content, not a mix of
+template and AI), 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

{plexavo-0.1.2 → plexavo-0.2.0}/plexavo/__init__.py

@@ -4,4 +4,4 @@ Runs entirely with your own local AWS credentials. Nothing is sent to
 anyone else. See README.md for usage, or `plexavo scan --help`.
 """
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"

plexavo-0.2.0/plexavo/aws_profile_setup.py

@@ -0,0 +1,66 @@
+"""plexavo/aws_profile_setup.py — writes a new named AWS profile to disk.
+
+Used by the interactive "+ Configure new profile" flow. Writes in the
+same layout `aws configure --profile NAME` itself produces:
+  ~/.aws/credentials  ->  [NAME]                 aws_access_key_id / aws_secret_access_key
+  ~/.aws/config       ->  [profile NAME]         region
+                          (bare [default] for the "default" profile)
+
+Only the target profile's section is added/updated — every other
+section in either file is read back untouched via configparser's
+read-modify-write round trip. One known limitation: configparser does
+not preserve comment lines on rewrite, so hand-written comments in
+these files (uncommon, since they're normally CLI/tool-managed) would
+be dropped. Actual key/value data for every other profile is preserved
+exactly.
+
+Respects AWS_SHARED_CREDENTIALS_FILE / AWS_CONFIG_FILE if set, same as
+the AWS CLI and boto3 itself.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+from pathlib import Path
+
+
+def credentials_path() -> Path:
+    return Path(os.environ.get("AWS_SHARED_CREDENTIALS_FILE", "~/.aws/credentials")).expanduser()
+
+
+def config_path() -> Path:
+    return Path(os.environ.get("AWS_CONFIG_FILE", "~/.aws/config")).expanduser()
+
+
+def _write_ini(path: Path, section: str, values: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    parser = configparser.ConfigParser()
+    if path.exists():
+        parser.read(path)
+    if not parser.has_section(section):
+        parser.add_section(section)
+    for key, value in values.items():
+        parser.set(section, key, value)
+    with open(path, "w", encoding="utf-8") as f:
+        parser.write(f)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        # Windows doesn't support POSIX file-mode bits the same way —
+        # best-effort only, same as the AWS CLI itself does here.
+        pass
+
+
+def write_profile(name: str, access_key_id: str, secret_access_key: str, region: str) -> None:
+    """Write/overwrite one named profile's credentials and region.
+
+    Never logs or returns the secret — callers must not print it either.
+    """
+    _write_ini(credentials_path(), name, {
+        "aws_access_key_id": access_key_id,
+        "aws_secret_access_key": secret_access_key,
+    })
+
+    config_section = "default" if name == "default" else f"profile {name}"
+    _write_ini(config_path(), config_section, {"region": region})