plexavo 0.3.0__tar.gz → 0.4.0__tar.gz

plexavo-0.4.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: plexavo
+Version: 0.4.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
+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)? 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), 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.
+
+## 📊 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>

plexavo-0.4.0/README.md

@@ -0,0 +1,227 @@
+<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)? 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), 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.
+
+## 📊 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>

{plexavo-0.3.0 → plexavo-0.4.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.3.0"
+__version__ = "0.4.0"

{plexavo-0.3.0 → plexavo-0.4.0}/plexavo/cli.py

@@ -12,6 +12,7 @@ credentials, the same way `aws s3 ls` does.
 """
 
 import argparse
+import json
 import os
 import random
 import sys
@@ -38,6 +39,7 @@ from plexavo.findings import Severity
 from plexavo.scoring import calculate_score
 from plexavo.report.ai_narration import explain_finding, COMMON_CHECK_TEMPLATES
 from plexavo.report.html_report import build_report_data, generate_html
+from plexavo.report.json_report import build_json_report
 from plexavo.report.pdf import generate_pdf
 
 console = Console()
@@ -147,10 +149,34 @@ def _build_parser() -> argparse.ArgumentParser:
                             "non-zero exit makes GitHub Actions or cron flag the run, so a regression "
                             "reaches you without opening a report by hand. Exit 1 still means the scan "
                             "itself could not run. Off by default. See docs/automation.md.")
+    scan.add_argument("--format", choices=["json"], default=None,
+                       help="Print one machine-readable JSON object to stdout instead of the normal "
+                            "console output (findings table, panels, progress) — that output still "
+                            "happens, it just goes to stderr, so stdout is always exactly one valid "
+                            "JSON object. Meant for a calling agent/script, not a person at a terminal. "
+                            "--report-html/--report-pdf still write their files as normal alongside it.")
     return parser
 
 
 def _run_scan(args) -> None:
+    """Thin wrapper around _run_scan_impl: when --format json is set,
+    every existing console.print call in the impl still runs unchanged,
+    it's just redirected to stderr for the duration, so stdout stays
+    exactly one JSON object printed via plain print() at the end. Always
+    restored afterward (try/finally), including on sys.exit paths, so a
+    later in-process call (tests, or a future caller) never inherits a
+    silently-redirected console."""
+    json_mode = args.format == "json"
+    original_file = console.file
+    if json_mode:
+        console.file = sys.stderr
+    try:
+        _run_scan_impl(args, json_mode)
+    finally:
+        console.file = original_file
+
+
+def _run_scan_impl(args, json_mode: bool) -> None:
     console.print(f"[bold]Using AWS profile:[/bold] {args.profile or '(default)'}")
     try:
         session = get_local_session(profile_name=args.profile, region=args.region)
@@ -168,7 +194,11 @@ def _run_scan(args) -> None:
     # False (confirmed — Rich only renders it in real terminals), so
     # scripting users get the exact same plain progress lines as before,
     # not silence. This is a deliberate branch, not an oversight.
-    is_tty = console.is_terminal
+    # Forced off in json_mode regardless of the actual terminal, so
+    # progress always uses plain print-per-stage lines (to stderr), never
+    # a Rich Live/Status spinner — deterministic output for a calling
+    # agent/script, not a cosmetic call.
+    is_tty = console.is_terminal and not json_mode
     findings = []
     principals = []
     chains = []
@@ -244,6 +274,8 @@ def _run_scan(args) -> None:
     # never make it into a report.
     if not findings and not chains:
         console.print("[green]No findings.[/green]")
+        if json_mode:
+            print(json.dumps(build_json_report(findings, result, account_id, [], chains=chains), indent=2))
         _apply_fail_on(args.fail_on, findings)
         return
 
@@ -352,6 +384,10 @@ def _run_scan(args) -> None:
             generate_pdf(report_data, args.report_pdf)
             console.print(f"[green]PDF report written to {os.path.abspath(args.report_pdf)}[/green]")
 
+    if json_mode:
+        json_payload = build_json_report(findings, result, account_id, explanations, chains=chains)
+        print(json.dumps(json_payload, indent=2))
+
     # Last thing in the scan: any report is on disk by now, so a non-zero
     # exit here never costs you the report.
     _apply_fail_on(args.fail_on, findings)

{plexavo-0.3.0 → plexavo-0.4.0}/plexavo/interactive.py

@@ -328,4 +328,5 @@ def run_interactive() -> None:
         report_html=options["report_html"],
         report_pdf=options["report_pdf"],
         fail_on=None,  # scheduled-run flag only; a person watching the score doesn't need it
+        format=None,  # agent/script output mode only; interactive mode always shows the normal console UI
     ))

plexavo-0.4.0/plexavo/report/json_report.py

@@ -0,0 +1,104 @@
+"""report/json_report.py — machine-readable JSON output, additive
+alongside the existing HTML/PDF reports (see html_report.py). Built for
+agent/orchestration callers (the Claude Code Agent Skill this feeds) that
+need a stable, parseable shape rather than rendered markup.
+
+This module never computes anything new. It reuses the exact same
+findings/score/chain objects every report already gets from _run_scan,
+including _chain_report_views (the same chain-dedup/badge logic the HTML
+Important tab uses) — a JSON consumer must see the identical picture a
+human reading the HTML report would, never a second, independently
+derived interpretation.
+
+schema_version is bumped only on a breaking shape change, so a consumer
+(the Skill) can pin to a known version and fail loudly instead of
+silently misparsing a future release.
+"""
+
+from datetime import datetime, timezone
+
+from plexavo import __version__
+from plexavo.report.html_report import _chain_report_views
+
+SCHEMA_VERSION = "1.0"
+
+# Limitations that must stay disclosed in every surface Plexavo ships,
+# this one included — never let a machine-readable summary imply broader
+# coverage than what actually ran, per the no-optics-tuning rule.
+DISCLOSED_LIMITATIONS = [
+    "Attack-path detection covers single-account chains only, matched against "
+    "two hardcoded templates — not an exhaustive graph traversal.",
+    "Privilege-escalation detection is one-hop only.",
+    "Cross-account trust resolution is not performed.",
+]
+
+
+def build_json_report(findings, score_result, account_id, explanations=None, chains=None) -> dict:
+    """Same inputs as html_report.build_report_data — a second view over
+    the identical scan output, not a second computation of it.
+
+    Findings are ordered most-severe-first (Critical -> Low), matching how
+    the HTML report groups them, so a consumer presenting "top findings
+    first" doesn't need to re-sort. Where a resource has more than one
+    finding, `findings_by_resource_arn` (used to back attack-chain nodes
+    with real finding content) keeps the most severe one, same rule
+    build_report_data uses.
+    """
+    if explanations is None:
+        explanations = [None] * len(findings)
+    if len(explanations) != len(findings):
+        raise ValueError(
+            f"explanations must be the same length as findings ({len(findings)}), "
+            f"got {len(explanations)} — pass None for any unexplained finding, not a shorter list"
+        )
+
+    paired = sorted(zip(findings, explanations), key=lambda pair: -pair[0].severity.rank)
+
+    findings_view = []
+    findings_by_resource_arn = {}
+    for f, exp in paired:
+        if exp is not None:
+            impact, how_to_fix, next_step = exp.impact, exp.how_to_fix, exp.next_step
+            # Same derivation build_report_data uses: judged from actual
+            # content, not exp.source, so "fallback"/"api-unparsed" (which
+            # carry the same empty how_to_fix/next_step shape as "never
+            # attempted") don't falsely claim to be explained.
+            explained = bool(how_to_fix) and bool(next_step)
+        else:
+            impact, how_to_fix, next_step, explained = f.raw_detail, "", "", False
+
+        entry = {
+            "check_id": f.check_id,
+            "title": f.title,
+            "severity": f.severity.value,
+            "resource": f.resource_arn.rsplit("/", 1)[-1] if "/" in f.resource_arn else f.resource_arn,
+            "resource_arn": f.resource_arn,
+            "confidence": f.confidence,
+            "evidence": f.evidence,
+            "impact": impact,
+            "explained": explained,
+            "next_step": next_step,
+            "how_to_fix": how_to_fix,
+            "chain_breaks_count": f.chain_breaks_count,
+        }
+        findings_view.append(entry)
+        findings_by_resource_arn.setdefault(f.resource_arn, entry)
+
+    chains_view, important_findings = _chain_report_views(chains or [], findings_by_resource_arn)
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "plexavo_version": __version__,
+        "account_id": account_id,
+        "scan_date": datetime.now(timezone.utc).strftime("%Y-%m-%d"),
+        "score": score_result.score,
+        "rating": score_result.rating,
+        "summary_line": score_result.summary_line(),
+        "counts_by_severity": score_result.counts_by_severity,
+        "counts_by_category": score_result.counts_by_category,
+        "total_findings": score_result.total_findings,
+        "findings": findings_view,
+        "attack_chains": chains_view,
+        "important_findings": important_findings,
+        "disclosed_limitations": DISCLOSED_LIMITATIONS,
+    }