plexavo 0.2.8__tar.gz → 0.3.0__tar.gz

{plexavo-0.2.8 → plexavo-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.2.8
+Version: 0.3.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
@@ -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.8 → plexavo-0.3.0}/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.8 → plexavo-0.3.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.2.8"
+__version__ = "0.3.0"

plexavo-0.3.0/plexavo/attack_paths.py

@@ -0,0 +1,398 @@
+"""Attack-path chaining: connects findings and relationship data from
+existing checks into end-to-end attack paths, when a real, unblocked
+connection exists between them - not just findings that happen to
+co-occur in the same scan.
+
+Runs after all other checks complete. Capped at MAX_CHAINS chains - a
+curated top-N of the clearest paths, not an exhaustive graph traversal
+(the build plan is explicit: 2-3 hardcoded templates, no generic graph
+engine).
+
+Every edge that depends on an IAM policy grant is verified against the
+same Deny/permission-boundary standard the one-hop IAM escalation checks
+already use (plexavo/principals.py: find_blocking_deny,
+action_within_boundary), and the same admin-equivalence heuristic
+(plexavo/checks/iam.py: is_admin_equivalent) - reused directly here, not
+reimplemented, so this can never silently drift from what those checks
+already consider "actually exploitable." A chain that looks plausible on
+the policy alone but is actually blocked in practice must never be shown
+as real - this is the accuracy risk the build plan calls out as more
+important than shipping fast.
+
+Two templates, both requiring the entry EC2 instance to be internet-
+exposed on some port (the same exposure data analyze_security_groups
+already computes for NET-01/02/03, just read for chain purposes too):
+
+- ec2-role-s3:   Internet -> EC2 -> IAM role (attached via instance
+                 profile) -> S3 bucket (the role's own policy grants
+                 GetObject/PutObject/DeleteObject on it).
+- ec2-role-role: Internet -> EC2 -> IAM role (attached via instance
+                 profile) -> another, admin-equivalent IAM role (the
+                 first role can sts:AssumeRole into it, whether that
+                 grant names the target role specifically - the IAM-05
+                 relationship - or is a Resource:* wildcard grant - the
+                 IAM-06 relationship) - re-scoped to just this one role
+                 rather than every principal in the account. Tried
+                 before ec2-role-s3 when both match the same instance:
+                 reaching an admin-equivalent role is account-wide
+                 compromise, a strictly worse outcome than one bucket's
+                 data, so it's the story that should surface.
+
+Deliberately out of scope, per the build plan: cross-account trust
+resolution, and any chain shape beyond these two fixed templates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from botocore.exceptions import ClientError
+
+from plexavo.findings import Finding
+from plexavo.principals import (
+    Principal,
+    _normalize,
+    find_blocking_deny,
+    action_within_boundary,
+    statement_grants,
+    resource_is_wildcard,
+)
+from plexavo.checks.network import analyze_security_groups, ADMIN_PORTS, DATABASE_PORTS
+from plexavo.checks.iam import is_admin_equivalent
+
+MAX_CHAINS = 2
+
+S3_DATA_ACTIONS = {"s3:GetObject", "s3:PutObject", "s3:DeleteObject"}
+
+
+@dataclass
+class ChainNode:
+    kind: str                    # "internet" | "ec2" | "iam-role" | "s3"
+    title: str                    # e.g. "EC2 instance"
+    detail: str                    # human-readable, e.g. "i-0a3f9c21 - sg-0d41 allows port 22 from the internet"
+    resource_id: str               # stable, slug-friendly id for this node - instance id / role
+                                     # name / bucket name. Used for the report's clickable jump
+                                     # anchors (#3) and as the key for chain-participation counting.
+    check_id: str | None = None    # an existing Finding this node is grounded in (e.g. "NET-01"), if any
+    finding_resource_arn: str | None = None  # the exact Finding.resource_arn form this node
+                                               # corresponds to (e.g. the role's full ARN, not just
+                                               # its name) - used only to link this node back to a
+                                               # real Finding for chain-impact purposes
+                                               # (apply_chain_impact below). None for the "internet"
+                                               # node, which isn't a scannable resource at all.
+
+
+@dataclass
+class AttackChain:
+    chain_id: str                  # "path-1", "path-2"
+    template: str                   # "ec2-role-s3" | "ec2-role-role"
+    nodes: list = field(default_factory=list)
+
+
+def _exposure_detail(sg_map: dict, sg_ids: list) -> tuple[str, str] | None:
+    """(sg_id, human-readable exposure text) for the first sg among sg_ids
+    that's actually open to the internet, or None. Reads the exact
+    exposure facts analyze_security_groups already computes for
+    NET-01/02/03 - no new exposure logic, just a different presentation
+    of the same data."""
+    for sg_id in sg_ids:
+        info = sg_map.get(sg_id)
+        if not info:
+            continue
+        if info["all_ports_open"]:
+            scope = "all ports and protocols" if info["all_protocols"] else "all ports (one protocol)"
+            return sg_id, f"{info['name']} ({sg_id}) allows {scope} from the internet"
+        if info["open_ranges"]:
+            lo, hi = info["open_ranges"][0]
+            label = ADMIN_PORTS.get(lo) or DATABASE_PORTS.get(lo)
+            port_desc = f"port {lo}" if lo == hi else f"ports {lo}-{hi}"
+            if label:
+                port_desc += f" ({label})"
+            return sg_id, f"{info['name']} ({sg_id}) allows {port_desc} from the internet"
+    return None
+
+
+def _resolve_instance_profile_role(iam, profile_arn: str) -> str | None:
+    profile_name = profile_arn.rsplit("/", 1)[-1]
+    try:
+        profile = iam.get_instance_profile(InstanceProfileName=profile_name)["InstanceProfile"]
+    except ClientError:
+        return None
+    roles = profile.get("Roles", [])
+    return roles[0]["Arn"] if roles else None
+
+
+def _list_exposed_instances_with_role(ec2, iam) -> list[dict]:
+    """Public, running/pending EC2 instances that are internet-exposed on
+    some port AND have an IAM instance profile attached, resolved to the
+    role's ARN.
+
+    New data collection: describe_instances already returns
+    IamInstanceProfile, but nothing in the codebase resolves that profile
+    to its role today. Deliberately NOT reusing network.py's
+    list_public_instances - that function is shared by NET-01/02/03/04
+    and already tested against a fixed tuple shape; this queries the same
+    API independently instead of changing a shipped function's contract.
+    """
+    sg_map = analyze_security_groups(ec2)
+    profile_role_cache: dict[str, str | None] = {}
+    results = []
+
+    paginator = ec2.get_paginator("describe_instances")
+    for page in paginator.paginate(Filters=[
+        {"Name": "instance-state-name", "Values": ["pending", "running"]}
+    ]):
+        for reservation in page["Reservations"]:
+            for instance in reservation["Instances"]:
+                public_ip = instance.get("PublicIpAddress")
+                if not public_ip:
+                    continue
+                profile = instance.get("IamInstanceProfile")
+                if not profile or not profile.get("Arn"):
+                    continue
+                sg_ids = [sg["GroupId"] for sg in instance.get("SecurityGroups", [])]
+                exposure = _exposure_detail(sg_map, sg_ids)
+                if not exposure:
+                    continue
+                sg_id, exposure_text = exposure
+
+                profile_arn = profile["Arn"]
+                if profile_arn not in profile_role_cache:
+                    profile_role_cache[profile_arn] = _resolve_instance_profile_role(iam, profile_arn)
+                role_arn = profile_role_cache[profile_arn]
+                if not role_arn:
+                    continue
+
+                name = next(
+                    (t["Value"] for t in instance.get("Tags", []) if t["Key"] == "Name"),
+                    instance["InstanceId"],
+                )
+                results.append({
+                    "instance_id": instance["InstanceId"],
+                    "name": name,
+                    "public_ip": public_ip,
+                    "sg_id": sg_id,
+                    "exposure_text": exposure_text,
+                    "role_arn": role_arn,
+                })
+    return results
+
+
+def _role_s3_grants(principal: Principal, bucket_names: list[str]) -> list[tuple[str, set]]:
+    """Buckets this role's own policies grant s3:GetObject/PutObject/
+    DeleteObject on (directly, or via s3:*/Action:* wildcards -
+    _action_matches in principals.py already resolves those), that
+    survive Deny/permission-boundary verification. Returns
+    [(bucket_name, granted_actions)].
+
+    Resource matching is a deliberate prefix check against the bucket's
+    own ARN (exact bucket ARN, or anything under "bucket/") rather than
+    principals.resource_includes' exact-match - a policy scoped to a
+    sub-prefix or a specific key still genuinely grants access into this
+    bucket, and missing that would be a false negative on a real path.
+    """
+    grants: dict[str, set] = {}
+    for _policy_name, statements in principal.policies:
+        for stmt in statements:
+            if stmt.get("Effect") != "Allow":
+                continue
+            granted = statement_grants(stmt, S3_DATA_ACTIONS)
+            if not granted:
+                continue
+            resources = _normalize(stmt.get("Resource"))
+            is_wildcard = resource_is_wildcard(stmt)
+            for bucket in bucket_names:
+                bucket_arn = f"arn:aws:s3:::{bucket}"
+                matches = is_wildcard or any(
+                    r == bucket_arn or r.startswith(bucket_arn + "/") for r in resources
+                )
+                if not matches:
+                    continue
+                grants.setdefault(bucket, set()).update(granted)
+
+    confirmed = []
+    for bucket, actions in grants.items():
+        # Representative resource ARN for the Deny/boundary check, same
+        # approximation pattern checks/iam.py's check_04 already uses
+        # when passing a single representative target_role_arn.
+        representative_arn = f"arn:aws:s3:::{bucket}/*"
+        still_granted = set()
+        for action in actions:
+            blocked, conditioned = find_blocking_deny(principal, action, representative_arn)
+            if blocked and not conditioned:
+                continue
+            if not action_within_boundary(principal, action, representative_arn):
+                continue
+            still_granted.add(action)
+        if still_granted:
+            confirmed.append((bucket, still_granted))
+    return confirmed
+
+
+def _role_admin_assume_targets(principal: Principal, admin_roles: dict) -> list[tuple[str, str]]:
+    """Admin-equivalent roles this principal can sts:AssumeRole into,
+    verified against Deny/boundary - the same relationship IAM-05 checks,
+    re-scoped to just this one principal instead of every principal in
+    the account, PLUS the IAM-06 (wildcard AssumeRole) relationship
+    folded in: a Resource:* grant means every admin-equivalent role is a
+    candidate target, each still verified individually against
+    Deny/boundary before being accepted. Deliberately broader than a
+    literal replay of check_05 alone - excluding the wildcard case would
+    mean the single most dangerous grant (assume ANY role) produces no
+    chain while a narrower, less severe one does, which is exactly
+    backwards for a feature whose job is showing real risk.
+    admin_roles is {role_arn: role_name}."""
+    targets = []
+    for _policy_name, statements in principal.policies:
+        for stmt in statements:
+            if stmt.get("Effect") != "Allow":
+                continue
+            if not statement_grants(stmt, {"sts:AssumeRole"}):
+                continue
+            if resource_is_wildcard(stmt):
+                candidate_arns = set(admin_roles)
+            else:
+                candidate_arns = set(_normalize(stmt.get("Resource"))) & set(admin_roles)
+            for target_arn in sorted(candidate_arns):
+                if target_arn == principal.arn:
+                    continue
+                blocked, conditioned = find_blocking_deny(principal, "sts:AssumeRole", target_arn)
+                if blocked and not conditioned:
+                    continue
+                if not action_within_boundary(principal, "sts:AssumeRole", target_arn):
+                    continue
+                targets.append((target_arn, admin_roles[target_arn]))
+    return targets
+
+
+def build_attack_chains(session, principals: list[Principal]) -> list[AttackChain]:
+    """Build up to MAX_CHAINS attack chains from this scan's data.
+    Single-account only - cross-account trust resolution is explicitly
+    out of scope (see module docstring and the build plan).
+
+    At most one chain per exposed instance (the first template that
+    matches - role-to-admin-role tried before S3, since reaching an
+    admin-equivalent role is account-wide compromise and a strictly
+    worse outcome than one bucket's data; showing the S3 path instead
+    when both exist would bury the more severe story), so two instances
+    that happen to share the same role/grant don't both spend the
+    two-chain budget on near-duplicate paths."""
+    ec2 = session.client("ec2")
+    iam = session.client("iam")
+    s3 = session.client("s3")
+
+    exposed = _list_exposed_instances_with_role(ec2, iam)
+    if not exposed:
+        return []
+
+    roles_by_arn = {p.arn: p for p in principals if p.type == "role"}
+    admin_roles = {
+        p.arn: p.name for p in principals
+        if p.type == "role" and is_admin_equivalent(p)
+    }
+    bucket_names = [b["Name"] for b in s3.list_buckets()["Buckets"]]
+
+    chains: list[AttackChain] = []
+
+    for entry in exposed:
+        if len(chains) >= MAX_CHAINS:
+            break
+        role = roles_by_arn.get(entry["role_arn"])
+        if role is None:
+            continue
+
+        internet_node = ChainNode(
+            kind="internet", title="Internet", detail="Unauthenticated, from anywhere",
+            resource_id="internet",
+        )
+        ec2_node = ChainNode(
+            kind="ec2", title="EC2 instance",
+            detail=f"{entry['instance_id']} - {entry['exposure_text']}",
+            resource_id=entry["instance_id"],
+            finding_resource_arn=entry["instance_id"],  # NET-01/02/03 use the bare instance id as resource_arn too
+        )
+        role_node = ChainNode(
+            kind="iam-role", title="IAM role",
+            detail=f"{role.name} - attached via instance profile",
+            resource_id=role.name,
+            finding_resource_arn=role.arn,
+        )
+
+        assume_targets = _role_admin_assume_targets(role, admin_roles)
+        if assume_targets:
+            target_arn, target_name = assume_targets[0]
+            target_role_node = ChainNode(
+                kind="iam-role", title="IAM role",
+                detail=f"{target_name} - admin-equivalent, reachable via sts:AssumeRole",
+                resource_id=target_name,
+                finding_resource_arn=target_arn,
+            )
+            chains.append(AttackChain(
+                chain_id=f"path-{len(chains) + 1}", template="ec2-role-role",
+                nodes=[internet_node, ec2_node, role_node, target_role_node],
+            ))
+            continue
+
+        s3_grants = _role_s3_grants(role, bucket_names)
+        if s3_grants:
+            bucket, actions = s3_grants[0]
+            s3_node = ChainNode(
+                kind="s3", title="S3 bucket",
+                detail=f"{bucket} - role policy grants {', '.join(sorted(actions))}",
+                finding_resource_arn=f"arn:aws:s3:::{bucket}",
+                resource_id=bucket,
+            )
+            chains.append(AttackChain(
+                chain_id=f"path-{len(chains) + 1}", template="ec2-role-s3",
+                nodes=[internet_node, ec2_node, role_node, s3_node],
+            ))
+
+    return chains
+
+
+def compute_chain_participation(chains: list[AttackChain]) -> dict:
+    """For every (kind, resource_id) node across all given chains
+    (excluding the "internet" node - not a fixable resource), how many
+    of those chains it appears in. This is the actual prioritization
+    signal the build plan calls for: remediating a node that appears in
+    N chains breaks all N of them at once - severity alone doesn't tell
+    you that.
+
+    Returns {(kind, resource_id): count}. The denominator for a "breaks
+    N of M" display is simply len(chains) - the total chains this scan
+    produced (capped at MAX_CHAINS)."""
+    counts: dict = {}
+    for chain in chains:
+        # A set, not a list - a node kind could in principle repeat within
+        # one chain (it doesn't with the current two templates, but this
+        # stays correct if a future template ever revisits a resource).
+        node_keys = {(n.kind, n.resource_id) for n in chain.nodes if n.kind != "internet"}
+        for key in node_keys:
+            counts[key] = counts.get(key, 0) + 1
+    return counts
+
+
+def apply_chain_impact(findings: list[Finding], chains: list[AttackChain]) -> None:
+    """Sets Finding.chain_breaks_count on every finding whose resource_arn
+    matches a chain node's finding_resource_arn - e.g. the EC2 instance
+    behind a chain's entry point is very likely already flagged by
+    NET-01/02/03, and that existing finding now carries "this sits inside
+    N attack chain(s)" as prioritization metadata.
+
+    Mutates findings in place; findings not touched by any chain are left
+    at the dataclass default of 0. Purely additive - never reads or
+    writes severity or score_penalty. See the no-optics-tuning rule: this
+    changes how findings are PRIORITIZED for reading order, never what
+    was detected or how severe it's scored."""
+    node_counts = compute_chain_participation(chains)
+    resource_to_count: dict = {}
+    for chain in chains:
+        for node in chain.nodes:
+            if node.finding_resource_arn is None:
+                continue
+            count = node_counts.get((node.kind, node.resource_id), 0)
+            existing = resource_to_count.get(node.finding_resource_arn, 0)
+            resource_to_count[node.finding_resource_arn] = max(existing, count)
+
+    for finding in findings:
+        finding.chain_breaks_count = resource_to_count.get(finding.resource_arn, 0)

{plexavo-0.2.8 → plexavo-0.3.0}/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
@@ -25,6 +26,7 @@ from rich.table import Table
 from plexavo import __version__
 from plexavo.auth import get_local_session, get_account_id
 from plexavo.principals import list_all_principals
+from plexavo import attack_paths
 from plexavo.checks import iam as iam_checks
 from plexavo.checks import iam_hygiene
 from plexavo.checks import network as network_checks
@@ -32,6 +34,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 +62,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 +141,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
 
 
@@ -119,8 +171,9 @@ def _run_scan(args) -> None:
     is_tty = console.is_terminal
     findings = []
     principals = []
+    chains = []
     stage_num = 0
-    total_stages = 8
+    total_stages = 9
     start_time = time.monotonic()
     flavor_pool = FLAVOR_WORDS.copy()
     random.shuffle(flavor_pool)
@@ -167,6 +220,10 @@ def _run_scan(args) -> None:
         stage("Running checks USE-26, USE-27 (usage analysis)")
         findings += usage_checks.run_all(session, principals)
 
+        stage("Building attack-path chains")
+        chains = attack_paths.build_attack_chains(session, principals)
+        attack_paths.apply_chain_impact(findings, chains)
+
     result = calculate_score(findings)
     rating_color = {"Excellent": "green", "Good": "green", "Fair": "yellow", "Poor": "orange3", "Critical": "red"}
     console.print(f"\n[bold {rating_color[result.rating]}]{result.summary_line()}[/bold {rating_color[result.rating]}]")
@@ -176,8 +233,18 @@ def _run_scan(args) -> None:
     else:
         console.print()
 
-    if not findings:
+    if chains:
+        console.print(f"[bold]{len(chains)} attack path{'s' if len(chains) != 1 else ''} identified[/bold] "
+                       f"— see the Visual Attack Path tab in the HTML report for detail.\n")
+
+    # Chains use their own independent exposure/relationship data, not
+    # the findings list — in principle a chain can exist even when every
+    # individual check came back clean, so "nothing to report" means both
+    # are empty, not just findings. Otherwise a real chain would silently
+    # never make it into a report.
+    if not findings and not chains:
         console.print("[green]No findings.[/green]")
+        _apply_fail_on(args.fail_on, findings)
         return
 
     table = Table(title=f"Findings ({len(findings)})")
@@ -270,7 +337,7 @@ def _run_scan(args) -> None:
             console.print("\n[yellow]Report includes free template remediation where available, raw technical "
                            "detail otherwise — pass --explain for full AI-written explanations on every "
                            "finding instead.[/yellow]")
-        report_data = build_report_data(findings, result, account_id, explanations)
+        report_data = build_report_data(findings, result, account_id, explanations, chains=chains)
 
         if args.report_html:
             html = generate_html(report_data)
@@ -285,6 +352,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.8 → plexavo-0.3.0}/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:
@@ -35,6 +48,12 @@ class Finding:
     evidence: str = ""       # the concrete account-state fact backing this finding — e.g.
                               # "granted=15, used=0, unused=15" or "last_used=never" — shown to the
                               # reader directly, not just fed silently into the AI prompt
+    chain_breaks_count: int = 0  # how many attack chains (plexavo/attack_paths.py) touch this
+                                   # finding's resource_arn — 0 means it isn't part of any chain.
+                                   # Set in a post-processing pass strictly after chains are built
+                                   # (attack_paths.apply_chain_impact), never during detection.
+                                   # Pure prioritization metadata — deliberately never feeds
+                                   # severity or score_penalty, see the no-optics-tuning rule.
 
     def to_dict(self) -> dict:
         return {
@@ -46,4 +65,5 @@ class Finding:
             "account_context": self.account_context,
             "confidence": self.confidence,
             "evidence": self.evidence,
+            "chain_breaks_count": self.chain_breaks_count,
         }

{plexavo-0.2.8 → plexavo-0.3.0}/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
     ))