plexavo 0.4.7__tar.gz → 0.4.8__tar.gz

{plexavo-0.4.7 → plexavo-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.4.7
+Version: 0.4.8
 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

{plexavo-0.4.7 → plexavo-0.4.8}/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.4.7"
+__version__ = "0.4.8"

{plexavo-0.4.7 → plexavo-0.4.8}/plexavo/checks/usage.py

@@ -125,6 +125,13 @@ _KNOWN_DATA_PLANE_ACTIONS = {
     "sqs:sendmessage", "sqs:receivemessage", "sqs:deletemessage",
 }
 
+# How long after a role's CreateDate an empty RoleLastUsed is treated as
+# "AWS may not have propagated this yet" rather than "confirmed never
+# used" - see check_27_roles_not_assumed's docstring. 24h is a deliberate
+# multiple of the delay actually observed live (RoleLastUsed still empty
+# 20+ minutes after a genuine sts:AssumeRole call), not a guess.
+ROLE_LAST_USED_GRACE_HOURS = 24
+
 
 def _is_action_used(granted_action: str, used_actions: set) -> bool:
     """True if granted_action was actually used — checked directly, or
@@ -263,16 +270,52 @@ def check_27_roles_not_assumed(iam_roles_raw: list, lookback_days: int = 90) ->
     against real data before this. More importantly: recommending
     `iam:DeleteServiceLinkedRole` is genuinely risky if AWS is silently,
     legitimately depending on one — this check has no way to confirm
-    that either way, so it doesn't guess."""
+    that either way, so it doesn't guess.
+
+    A recently-created role with an empty RoleLastUsed is genuinely
+    ambiguous, not confidently "never assumed" — confirmed live while
+    testing the get_role fix above: a role assumed via a real
+    sts:AssumeRole call still showed RoleLastUsed={} more than 20 minutes
+    later, and AWS's own documentation states this data can take up to
+    several hours to propagate after actual use. This isn't specific to
+    a compressed test timeline either — the exact same thing happens to
+    any real role created and used for the first time shortly before a
+    scan (a CI/CD pipeline spinning up a role and immediately assuming
+    it, for example). ROLE_LAST_USED_GRACE_HOURS below downgrades that
+    specific, narrow case (empty RoleLastUsed AND created within the
+    grace window) to "Likely — see note" at reduced severity, rather
+    than asserting Confirmed either way — never silently suppressed
+    (a role that's genuinely never been used still gets a full-confidence
+    finding once the grace window passes), never falsely certain while
+    AWS's own data could still be catching up. Deliberately scoped
+    per-role, not account-wide: an account where truly nothing has been
+    used yet is a real, common, accurately-reported case (see module
+    docstring's low-activity-account note) — silencing this check
+    whenever no role anywhere shows RoleLastUsed would hide exactly that
+    signal instead of fixing an ambiguity."""
     findings = []
     cutoff = datetime.now(timezone.utc) - timedelta(days=lookback_days)
+    grace_cutoff = datetime.now(timezone.utc) - timedelta(hours=ROLE_LAST_USED_GRACE_HOURS)
     for role in iam_roles_raw:
         if role.get("Path", "").startswith("/aws-service-role/"):
             continue
         last_used = role.get("RoleLastUsed", {}).get("LastUsedDate")
         role_name = role["RoleName"]
         role_arn = role["Arn"]
+        severity = Severity.HIGH
+        confidence = "Confirmed"
+        ambiguity_note = ""
         if last_used is None:
+            create_date = role.get("CreateDate")
+            if create_date is not None and create_date > grace_cutoff:
+                severity = Severity.MEDIUM
+                confidence = "Likely — see note"
+                ambiguity_note = (
+                    f" Role was created less than {ROLE_LAST_USED_GRACE_HOURS}h ago — "
+                    f"AWS's RoleLastUsed data can take hours to propagate after actual use, "
+                    f"so an empty value here doesn't necessarily mean the role has never been "
+                    f"used, only that no use has been recorded yet."
+                )
             detail = f"Role '{role_name}' has never been assumed since it was created."
             last_used_str = "never"
         elif last_used < cutoff:
@@ -284,14 +327,15 @@ def check_27_roles_not_assumed(iam_roles_raw: list, lookback_days: int = 90) ->
         findings.append(Finding(
             check_id="USE-27",
             title="Role Not Assumed Recently",
-            severity=Severity.HIGH,
+            severity=severity,
             resource_arn=role_arn,
             raw_detail=(
                 f"{detail} An unused role is standing attack surface with no current legitimate "
                 f"purpose — confirm it's still needed, or remove it."
             ),
             account_context=f"last_used={last_used_str}",
-            evidence=f"last_used={last_used_str}",
+            confidence=confidence,
+            evidence=f"last_used={last_used_str}.{ambiguity_note}".strip(),
         ))
     return findings
 

{plexavo-0.4.7 → plexavo-0.4.8}/plexavo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.4.7
+Version: 0.4.8
 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

{plexavo-0.4.7 → plexavo-0.4.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plexavo"
-version = "0.4.7"
+version = "0.4.8"
 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.4.7 → plexavo-0.4.8}/tests/test_usage_offline.py

@@ -51,11 +51,12 @@ def assumed_role_event(role_arn, event_source, event_name):
     }
 
 
-def role_dict(name, last_used=None):
+def role_dict(name, last_used=None, create_date=None):
     return {
         "RoleName": name,
         "Arn": f"arn:aws:iam::111111111111:role/{name}",
         "RoleLastUsed": {"LastUsedDate": last_used} if last_used is not None else {},
+        "CreateDate": create_date,
     }
 
 
@@ -128,10 +129,12 @@ user_principal = [Principal(type="user", name="lab-admin", arn="arn:aws:iam::111
 findings = usage.check_26_unused_permissions(FakeCloudTrail([]), user_principal)
 assert_true(len(findings) == 0, "IAM users are not evaluated by this check — it's role-specific by design")
 
-print("\n=== check_27: fires on a role never assumed (RoleLastUsed empty) ===")
+print("\n=== check_27: fires on a role never assumed (RoleLastUsed empty), no CreateDate at all ===")
 roles = [role_dict("never-used-role")]
 findings = usage.check_27_roles_not_assumed(roles)
 assert_true(len(findings) == 1 and "never been assumed" in findings[0].raw_detail, "Fires with 'never assumed' wording")
+assert_true(findings[0].severity.value == "High" and findings[0].confidence == "Confirmed",
+            "No CreateDate at all falls through to the unchanged Confirmed/High behavior (defensive default)")
 
 print("\n=== check_27: fires on a role last assumed 120 days ago (over the 90-day window) ===")
 old_date = datetime.now(timezone.utc) - timedelta(days=120)
@@ -145,6 +148,35 @@ roles = [role_dict("active-role", last_used=recent_date)]
 findings = usage.check_27_roles_not_assumed(roles)
 assert_true(len(findings) == 0, "Does NOT fire on a recently-assumed role")
 
+print("\n=== FIX: a freshly-created role with empty RoleLastUsed downgrades instead of asserting Confirmed ===")
+# Confirmed live (2026-09-28): a role assumed via a real sts:AssumeRole call
+# still showed RoleLastUsed={} more than 20 minutes later — AWS's own
+# propagation can genuinely take hours, not just in this compressed test.
+just_created = datetime.now(timezone.utc) - timedelta(hours=1)
+roles = [role_dict("brand-new-role", create_date=just_created)]
+findings = usage.check_27_roles_not_assumed(roles)
+assert_true(len(findings) == 1, "Still fires — a Condition/grace period downgrades, never fully suppresses")
+assert_true(findings[0].severity.value == "Medium", f"Downgraded to Medium, not High (got: {findings[0].severity.value})")
+assert_true(findings[0].confidence == "Likely — see note", f"Confidence downgraded (got: {findings[0].confidence})")
+assert_true("propagate" in findings[0].evidence.lower(), "Evidence explains the AWS propagation ambiguity, not buried in raw_detail")
+
+print("\n=== REGRESSION: a role created well past the grace window stays at full Confirmed/High ===")
+long_ago = datetime.now(timezone.utc) - timedelta(hours=48)
+roles = [role_dict("old-unused-role", create_date=long_ago)]
+findings = usage.check_27_roles_not_assumed(roles)
+assert_true(len(findings) == 1, "Fires")
+assert_true(findings[0].severity.value == "High" and findings[0].confidence == "Confirmed",
+            "Past the grace window, stays at full Confirmed/High — the fix doesn't quietly weaken the check generally")
+
+print("\n=== REGRESSION: the grace period only applies to the empty-RoleLastUsed case, never a stale-but-real timestamp ===")
+stale_but_recent_role = datetime.now(timezone.utc) - timedelta(hours=1)
+old_last_used = datetime.now(timezone.utc) - timedelta(days=120)
+roles = [role_dict("stale-fresh-role", last_used=old_last_used, create_date=stale_but_recent_role)]
+findings = usage.check_27_roles_not_assumed(roles)
+assert_true(len(findings) == 1, "Fires")
+assert_true(findings[0].severity.value == "High" and findings[0].confidence == "Confirmed",
+            "A real (non-empty) stale LastUsedDate is unambiguous regardless of CreateDate — full Confirmed/High, no grace-period downgrade")
+
 print("\n=== check_27: exactly-90-days boundary — must fire (>=90, not >90) ===")
 boundary_date = datetime.now(timezone.utc) - timedelta(days=91)  # safely past 90 to avoid test-runtime flakiness
 roles = [role_dict("boundary-role", last_used=boundary_date)]