plexavo 0.2.7__tar.gz → 0.2.9__tar.gz

{plexavo-0.2.7 → plexavo-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.2.7
+Version: 0.2.9
 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
@@ -134,6 +134,12 @@ python -m plexavo   # Windows Option 2
   <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).
+
 ## The report
 
 Reports are generated as HTML, PDF, or both. Every finding gets a free,

{plexavo-0.2.7 → plexavo-0.2.9}/README.md

@@ -105,6 +105,12 @@ python -m plexavo   # Windows Option 2
   <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).
+
 ## The report
 
 Reports are generated as HTML, PDF, or both. Every finding gets a free,

{plexavo-0.2.7 → plexavo-0.2.9}/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.2.7"
+__version__ = "0.2.9"

{plexavo-0.2.7 → plexavo-0.2.9}/plexavo/checks/storage.py

@@ -139,7 +139,10 @@ def check_22_access_logging_disabled(s3, bucket_names: list) -> list[Finding]:
 
     Medium, not Critical: this is a forensics gap, not an exposure by
     itself — a bucket with logging off isn't more reachable than one with
-    it on, it's just unreviewable after the fact if something happens."""
+    it on. Whether object-level access is actually unreviewable after the
+    fact depends on whether it's captured another way (e.g. CloudTrail S3
+    data events), which Plexavo does not check — so the finding language
+    stays careful not to claim investigation is impossible."""
     findings = []
     for name in bucket_names:
         config = s3.get_bucket_logging(Bucket=name)
@@ -150,10 +153,13 @@ def check_22_access_logging_disabled(s3, bucket_names: list) -> list[Finding]:
             title="S3 Bucket Access Logging Not Enabled",
             severity=Severity.MEDIUM,
             resource_arn=f"arn:aws:s3:::{name}",
-            raw_detail=f"Bucket '{name}' has no server access logging configured. "
-                       f"If this bucket is ever accessed, modified, or exfiltrated "
-                       f"from, there is no record of who did what — investigation "
-                       f"after the fact isn't possible.",
+            raw_detail=f"Bucket '{name}' has no S3 server access logging configured. "
+                       f"Server access logging records object-level requests to the "
+                       f"bucket, which supports reconstructing who accessed or changed "
+                       f"what after the fact. If this bucket's access is already "
+                       f"tightly scoped and audited another way (for example CloudTrail "
+                       f"S3 data events, which Plexavo does not check), this finding may "
+                       f"be lower priority for that specific setup.",
             account_context=f"bucket={name}",
         ))
     return findings

{plexavo-0.2.7 → plexavo-0.2.9}/plexavo/cli.py

@@ -16,6 +16,7 @@ import os
 import random
 import sys
 import time
+from collections import Counter
 from contextlib import nullcontext
 
 from rich.console import Console
@@ -32,6 +33,7 @@ from plexavo.checks import storage as storage_checks
 from plexavo.checks import encryption as encryption_checks
 from plexavo.checks import logging as logging_checks
 from plexavo.checks import usage as usage_checks
+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
@@ -59,6 +61,49 @@ FLAVOR_WORDS = [
     "Scrutinizing bucket policies",
 ]
 
+# --fail-on keyword -> Severity. One entry per Severity member; the test
+# suite asserts that stays true.
+FAIL_ON_LEVELS = {
+    "critical": Severity.CRITICAL,
+    "high": Severity.HIGH,
+    "medium": Severity.MEDIUM,
+    "low": Severity.LOW,
+}
+
+# Exit status when --fail-on trips. Deliberately not 1: exit 1 already
+# means "the scan could not run" (bad creds, no region), which a
+# scheduled job wants to treat differently from "the scan ran fine and
+# found something at your threshold".
+FAIL_ON_EXIT_CODE = 2
+
+
+def _findings_at_or_above(findings, level: str) -> list:
+    """Findings whose severity is at or above `level` (a FAIL_ON_LEVELS key)."""
+    threshold = FAIL_ON_LEVELS[level].rank
+    return [f for f in findings if f.severity.rank >= threshold]
+
+
+def _apply_fail_on(level, findings) -> None:
+    """When --fail-on is set, exit FAIL_ON_EXIT_CODE if any finding is at
+    or above `level`. Called only after any report has been written, so a
+    failing run still leaves you the report."""
+    if not level:
+        return
+    triggering = _findings_at_or_above(findings, level)
+    label = level.capitalize()
+    if not triggering:
+        console.print(f"\n[green]--fail-on {level}: no findings at or above {label}.[/green]")
+        return
+    counts = Counter(f.severity.value for f in triggering)
+    breakdown = ", ".join(
+        f"{counts[s]} {s}" for s in ("Critical", "High", "Medium", "Low") if counts.get(s)
+    )
+    console.print(
+        f"\n[bold red]--fail-on {level}: {len(triggering)} finding(s) at or above "
+        f"{label} ({breakdown}). Exiting with status {FAIL_ON_EXIT_CODE}.[/bold red]"
+    )
+    sys.exit(FAIL_ON_EXIT_CODE)
+
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
@@ -95,6 +140,12 @@ def _build_parser() -> argparse.ArgumentParser:
                             "--explain replaces that with a full AI narrative for every finding instead.")
     scan.add_argument("--report-pdf", metavar="PATH", default=None,
                        help="Write a PDF report to PATH. Same --explain behavior as --report-html.")
+    scan.add_argument("--fail-on", choices=["critical", "high", "medium", "low"], default=None,
+                       help="After the scan, exit with status 2 if any finding is at or above this "
+                            "severity. Any report is still written first. Meant for scheduled runs: a "
+                            "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.")
     return parser
 
 
@@ -178,6 +229,7 @@ def _run_scan(args) -> None:
 
     if not findings:
         console.print("[green]No findings.[/green]")
+        _apply_fail_on(args.fail_on, findings)
         return
 
     table = Table(title=f"Findings ({len(findings)})")
@@ -285,6 +337,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]")
 
+    # 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)
+
 
 def main():
     parser = _build_parser()

{plexavo-0.2.7 → plexavo-0.2.9}/plexavo/findings.py

@@ -19,6 +19,19 @@ class Severity(Enum):
             Severity.LOW: 1,
         }[self]
 
+    @property
+    def rank(self) -> int:
+        """Ordering for threshold comparisons, Critical highest. Kept
+        separate from score_penalty: that one is a scoring weight, this
+        one is just an ordinal so `--fail-on` can ask "at or above X".
+        """
+        return {
+            Severity.CRITICAL: 4,
+            Severity.HIGH: 3,
+            Severity.MEDIUM: 2,
+            Severity.LOW: 1,
+        }[self]
+
 
 @dataclass
 class Finding:

{plexavo-0.2.7 → plexavo-0.2.9}/plexavo/interactive.py

@@ -327,4 +327,5 @@ def run_interactive() -> None:
         explain_limit=25,
         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
     ))

{plexavo-0.2.7 → plexavo-0.2.9}/plexavo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.2.7
+Version: 0.2.9
 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
@@ -134,6 +134,12 @@ python -m plexavo   # Windows Option 2
   <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).
+
 ## The report
 
 Reports are generated as HTML, PDF, or both. Every finding gets a free,

{plexavo-0.2.7 → plexavo-0.2.9}/plexavo.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ tests/test_ai_narration_offline.py
 tests/test_auth_offline.py
 tests/test_cli_entrypoint.py
 tests/test_encryption_offline.py
+tests/test_fail_on_offline.py
 tests/test_iam_hygiene_offline.py
 tests/test_iam_offline.py
 tests/test_logging_offline.py

{plexavo-0.2.7 → plexavo-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plexavo"
-version = "0.2.7"
+version = "0.2.9"
 description = "Open-source AWS misconfiguration scanner — runs with your own local AWS credentials, nothing sent to anyone else."
 readme = "README.md"
 license = { text = "AGPL-3.0-or-later" }

{plexavo-0.2.7 → plexavo-0.2.9}/tests/test_cli_entrypoint.py

@@ -47,5 +47,10 @@ assert_true("scan" in helptext.stdout, "help lists the scan subcommand")
 assert_true("usage: plexavo" in helptext.stdout,
             "usage line shows 'plexavo', not '__main__.py'")
 
+print("\n=== python -m plexavo scan --help documents --fail-on ===")
+scanhelp = run("-m", "plexavo", "scan", "--help")
+assert_true(scanhelp.returncode == 0, f"scan --help exits 0 (got {scanhelp.returncode})")
+assert_true("--fail-on" in scanhelp.stdout, "scan --help lists --fail-on")
+
 print(f"\n{'ALL PASSED' if failures == 0 else f'{failures} FAILURE(S)'}")
 sys.exit(1 if failures else 0)

plexavo-0.2.9/tests/test_fail_on_offline.py

@@ -0,0 +1,68 @@
+"""Offline tests for `plexavo scan --fail-on`: the severity threshold that
+makes a scheduled run exit non-zero when something is at or above it.
+
+Run: python test_fail_on_offline.py
+"""
+
+import sys
+
+from plexavo.cli import FAIL_ON_LEVELS, FAIL_ON_EXIT_CODE, _findings_at_or_above
+from plexavo.findings import Finding, Severity
+
+failures = 0
+
+
+def assert_true(cond, msg):
+    global failures
+    status = "PASS" if cond else "FAIL"
+    print(f"[{status}] {msg}")
+    if not cond:
+        failures += 1
+
+
+def finding(severity):
+    return Finding(
+        check_id="TST-01",
+        title="test",
+        severity=severity,
+        resource_arn="arn:aws:iam::123456789012:user/test",
+        raw_detail="test finding",
+    )
+
+
+print("=== Severity.rank ordering ===")
+assert_true(
+    Severity.CRITICAL.rank > Severity.HIGH.rank > Severity.MEDIUM.rank > Severity.LOW.rank,
+    "Critical > High > Medium > Low",
+)
+
+print("\n=== FAIL_ON_LEVELS covers every severity, once ===")
+assert_true(
+    set(FAIL_ON_LEVELS) == {"critical", "high", "medium", "low"},
+    "one --fail-on keyword per Severity member",
+)
+assert_true(FAIL_ON_EXIT_CODE != 0 and FAIL_ON_EXIT_CODE != 1, "trip exit code is non-zero and not 1")
+
+print("\n=== _findings_at_or_above ===")
+mixed = [
+    finding(Severity.LOW),
+    finding(Severity.MEDIUM),
+    finding(Severity.HIGH),
+    finding(Severity.CRITICAL),
+]
+assert_true(len(_findings_at_or_above(mixed, "high")) == 2,
+            "fail-on high matches the High and the Critical")
+assert_true(len(_findings_at_or_above(mixed, "critical")) == 1,
+            "fail-on critical matches only the Critical")
+assert_true(len(_findings_at_or_above(mixed, "medium")) == 3,
+            "fail-on medium matches Medium, High, Critical")
+assert_true(len(_findings_at_or_above(mixed, "low")) == 4,
+            "fail-on low matches everything")
+
+assert_true(_findings_at_or_above([], "critical") == [],
+            "no findings, nothing to trip on")
+assert_true(_findings_at_or_above([finding(Severity.LOW), finding(Severity.MEDIUM)], "high") == [],
+            "only Low/Medium present, fail-on high stays clean")
+
+print(f"\n{'ALL PASSED' if failures == 0 else f'{failures} FAILURE(S)'}")
+sys.exit(1 if failures else 0)