iam-policy-validator 1.14.7__py3-none-any.whl → 1.15.1__py3-none-any.whl

iam_validator/core/check_registry.py

@@ -15,6 +15,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
 from iam_validator.core.aws_service import AWSServiceFetcher
+from iam_validator.core.config.check_documentation import CheckDocumentationRegistry
 from iam_validator.core.ignore_patterns import IgnorePatternMatcher
 from iam_validator.core.models import Statement, ValidationIssue
 
@@ -22,6 +23,28 @@ if TYPE_CHECKING:
     from iam_validator.core.models import IAMPolicy
 
 
+def _inject_documentation(issue: ValidationIssue, check_id: str) -> None:
+    """Inject documentation fields from CheckDocumentationRegistry into an issue.
+
+    This populates risk_explanation, documentation_url, remediation_steps, and
+    risk_category from the centralized documentation registry if not already set.
+
+    Args:
+        issue: The validation issue to enhance
+        check_id: The check ID to look up documentation for
+    """
+    doc = CheckDocumentationRegistry.get(check_id)
+    if doc:
+        if issue.risk_explanation is None:
+            issue.risk_explanation = doc.risk_explanation
+        if issue.documentation_url is None:
+            issue.documentation_url = doc.documentation_url
+        if issue.remediation_steps is None:
+            issue.remediation_steps = doc.remediation_steps
+        if issue.risk_category is None:
+            issue.risk_category = doc.risk_category
+
+
 @dataclass
 class CheckConfig:
     """Configuration for a single check."""
@@ -32,28 +55,53 @@ class CheckConfig:
     config: dict[str, Any] = field(default_factory=dict)  # Check-specific config
     description: str = ""
     root_config: dict[str, Any] = field(default_factory=dict)  # Full config for cross-check access
-    ignore_patterns: list[dict[str, Any]] = field(default_factory=list)  # NEW: Ignore patterns
+    ignore_patterns: list[dict[str, Any]] = field(default_factory=list)  # Ignore patterns
+    hide_severities: frozenset[str] | None = None  # Severities to hide from output
     """
-    List of patterns to ignore findings.
-
-    Each pattern is a dict with optional fields:
-    - filepath: Regex to match file path
-    - action: Regex to match action name
-    - resource: Regex to match resource
-    - sid: Exact SID to match (or regex if ends with .*)
-    - condition_key: Regex to match condition key
-
-    Multiple fields in one pattern = AND logic
-    Multiple patterns = OR logic (any pattern matches → ignore)
-
-    Example:
-        ignore_patterns:
-          - filepath: "test/.*|examples/.*"
-          - filepath: "policies/readonly-.*"
-            action: ".*:(Get|List|Describe).*"
-          - sid: "AllowReadOnlyAccess"
+    Configuration fields:
+
+    ignore_patterns: List of patterns to ignore findings.
+        Each pattern is a dict with optional fields:
+        - filepath: Regex to match file path
+        - action: Regex to match action name
+        - resource: Regex to match resource
+        - sid: Exact SID to match (or regex if ends with .*)
+        - condition_key: Regex to match condition key
+
+        Multiple fields in one pattern = AND logic
+        Multiple patterns = OR logic (any pattern matches → ignore)
+
+        Example:
+            ignore_patterns:
+              - filepath: "test/.*|examples/.*"
+              - filepath: "policies/readonly-.*"
+                action: ".*:(Get|List|Describe).*"
+              - sid: "AllowReadOnlyAccess"
+
+    hide_severities: Set of severity levels to hide from output.
+        Issues with these severities will be filtered out and not shown
+        in any output (console, JSON, SARIF, GitHub PR comments, etc.).
+
+        Example:
+            hide_severities: frozenset(["low", "info"])
     """
 
+    def should_show_severity(self, severity: str) -> bool:
+        """Check if a severity level should be shown in output.
+
+        Returns False if severity is in hide_severities, True otherwise.
+        This is used to filter out low-priority findings to reduce noise.
+
+        Args:
+            severity: The severity level to check
+
+        Returns:
+            True if the severity should be shown, False if it should be hidden
+        """
+        if self.hide_severities and severity in self.hide_severities:
+            return False
+        return True
+
     def should_ignore(self, issue: ValidationIssue, filepath: str = "") -> bool:
         """
         Check if issue should be ignored based on ignore patterns.
@@ -425,13 +473,17 @@ class CheckRegistry:
                 config = self.get_config(check.check_id)
                 if config:
                     issues = await check.execute(statement, statement_idx, fetcher, config)
-                    # Inject check_id into each issue
+                    # Inject check_id and documentation into each issue
                     for issue in issues:
                         if issue.check_id is None:
                             issue.check_id = check.check_id
-                    # Filter issues based on ignore_patterns
+                        _inject_documentation(issue, check.check_id)
+                    # Filter issues based on ignore_patterns and hide_severities
                     filtered_issues = [
-                        issue for issue in issues if not config.should_ignore(issue, filepath)
+                        issue
+                        for issue in issues
+                        if not config.should_ignore(issue, filepath)
+                        and config.should_show_severity(issue.severity)
                     ]
                     all_issues.extend(filtered_issues)
             return all_issues
@@ -449,7 +501,7 @@ class CheckRegistry:
         # Wait for all checks to complete
         results = await asyncio.gather(*tasks, return_exceptions=True)
 
-        # Collect all issues, handling any exceptions and applying ignore_patterns
+        # Collect all issues, handling any exceptions and applying filters
         all_issues = []
         for idx, result in enumerate(results):
             if isinstance(result, Exception):
@@ -459,13 +511,17 @@ class CheckRegistry:
             elif isinstance(result, list):
                 check = enabled_checks[idx]
                 config = configs[idx]
-                # Inject check_id into each issue
+                # Inject check_id and documentation into each issue
                 for issue in result:
                     if issue.check_id is None:
                         issue.check_id = check.check_id
-                # Filter issues based on ignore_patterns
+                    _inject_documentation(issue, check.check_id)
+                # Filter issues based on ignore_patterns and hide_severities
                 filtered_issues = [
-                    issue for issue in result if not config.should_ignore(issue, filepath)
+                    issue
+                    for issue in result
+                    if not config.should_ignore(issue, filepath)
+                    and config.should_show_severity(issue.severity)
                 ]
                 all_issues.extend(filtered_issues)
 
@@ -499,7 +555,7 @@ class CheckRegistry:
                 try:
                     issues = await check.execute(statement, statement_idx, fetcher, config)
                     all_issues.extend(issues)
-                except Exception as e:
+                except Exception as e:  # pylint: disable=broad-exception-caught
                     print(f"Warning: Check '{check.check_id}' failed: {e}")
 
         return all_issues
@@ -551,18 +607,20 @@ class CheckRegistry:
                             policy_type=policy_type,
                             **kwargs,
                         )
-                        # Inject check_id into each issue
+                        # Inject check_id and documentation into each issue
                         for issue in issues:
                             if issue.check_id is None:
                                 issue.check_id = check.check_id
-                        # Filter issues based on ignore_patterns
+                            _inject_documentation(issue, check.check_id)
+                        # Filter issues based on ignore_patterns and hide_severities
                         filtered_issues = [
                             issue
                             for issue in issues
                             if not config.should_ignore(issue, policy_file)
+                            and config.should_show_severity(issue.severity)
                         ]
                         all_issues.extend(filtered_issues)
-                    except Exception as e:
+                    except Exception as e:  # pylint: disable=broad-exception-caught
                         print(f"Warning: Check '{check.check_id}' failed: {e}")
             return all_issues
 
@@ -581,7 +639,7 @@ class CheckRegistry:
         # Wait for all checks to complete
         results = await asyncio.gather(*tasks, return_exceptions=True)
 
-        # Collect all issues, handling any exceptions and applying ignore_patterns
+        # Collect all issues, handling any exceptions and applying filters
         for idx, result in enumerate(results):
             if isinstance(result, Exception):
                 # Log error but continue with other checks
@@ -590,13 +648,17 @@ class CheckRegistry:
             elif isinstance(result, list):
                 check = policy_level_checks[idx]
                 config = configs[idx]
-                # Inject check_id into each issue
+                # Inject check_id and documentation into each issue
                 for issue in result:
                     if issue.check_id is None:
                         issue.check_id = check.check_id
-                # Filter issues based on ignore_patterns
+                    _inject_documentation(issue, check.check_id)
+                # Filter issues based on ignore_patterns and hide_severities
                 filtered_issues = [
-                    issue for issue in result if not config.should_ignore(issue, policy_file)
+                    issue
+                    for issue in result
+                    if not config.should_ignore(issue, policy_file)
+                    and config.should_show_severity(issue.severity)
                 ]
                 all_issues.extend(filtered_issues)
 
@@ -623,7 +685,7 @@ def create_default_registry(
 
     if include_builtin_checks:
         # Import and register built-in checks
-        from iam_validator import checks
+        from iam_validator import checks  # pylint: disable=import-outside-toplevel
 
         # 0. FUNDAMENTAL STRUCTURE (Must run FIRST - validates basic policy structure)
         registry.register(
@@ -655,6 +717,9 @@ def create_default_registry(
         registry.register(checks.WildcardResourceCheck())  # Wildcard resource detection
         registry.register(checks.FullWildcardCheck())  # Full wildcard (*) detection
         registry.register(checks.ServiceWildcardCheck())  # Service-level wildcard detection
+        registry.register(
+            checks.NotActionNotResourceCheck()
+        )  # NotAction/NotResource pattern detection
 
         # 6. SECURITY - ADVANCED (Sensitive actions and condition enforcement)
         registry.register(

iam_validator/core/config/aws_global_conditions.py

@@ -71,18 +71,27 @@ AWS_GLOBAL_CONDITION_KEYS = {
     "aws:ViaAWSService": "Bool",  # Whether AWS service made the request
 }
 
+# Global condition keys that restrict resource scope.
+# These conditions are always valid for all services and directly constrain
+# which resources can be accessed, making them suitable for lowering severity
+# when used with wildcard resources.
+# Reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourceaccount
+GLOBAL_RESOURCE_SCOPING_CONDITION_KEYS = frozenset(
+    {
+        "aws:ResourceAccount",  # Limits to specific AWS account(s)
+        "aws:ResourceOrgID",  # Limits to specific AWS Organization
+        "aws:ResourceOrgPaths",  # Limits to specific OU paths
+    }
+)
+
 # Patterns that should be recognized (wildcards and tag-based keys)
-# These allow things like aws:RequestTag/Department or aws:PrincipalTag/Environment
+# IMPORTANT: aws:RequestTag and aws:ResourceTag are NOT global condition keys!
+# They are action-specific or resource-specific and must be explicitly listed in
+# the action's ActionConditionKeys or the resource's ConditionKeys.
+# Only aws:PrincipalTag is a true global condition key.
+#
 # Uses centralized tag key character class from constants
 AWS_CONDITION_KEY_PATTERNS = [
-    {
-        "pattern": rf"^aws:RequestTag/[{AWS_TAG_KEY_ALLOWED_CHARS}]+$",
-        "description": "Tag keys in the request (for tag-based access control)",
-    },
-    {
-        "pattern": rf"^aws:ResourceTag/[{AWS_TAG_KEY_ALLOWED_CHARS}]+$",
-        "description": "Tags on the resource being accessed",
-    },
     {
         "pattern": rf"^aws:PrincipalTag/[{AWS_TAG_KEY_ALLOWED_CHARS}]+$",
         "description": "Tags attached to the principal making the request",

iam_validator/core/config/check_documentation.py

@@ -9,6 +9,18 @@ Used to enhance ValidationIssue objects with actionable guidance.
 from dataclasses import dataclass, field
 from typing import ClassVar
 
+# Risk category icons for display in PR comments
+RISK_CATEGORY_ICONS = {
+    "privilege_escalation": "🔐",
+    "data_exfiltration": "📤",
+    "denial_of_service": "🚫",
+    "resource_exposure": "🌐",
+    "credential_exposure": "🔑",
+    "compliance": "📋",
+    "configuration": "⚙️",
+    "validation": "✅",
+}
+
 
 @dataclass
 class CheckDocumentation:
@@ -19,12 +31,14 @@ class CheckDocumentation:
         risk_explanation: Why this issue is a security risk
         documentation_url: Link to relevant AWS docs or runbook
         remediation_steps: Step-by-step fix guidance
+        risk_category: Category of risk (e.g., "privilege_escalation", "data_exfiltration")
     """
 
     check_id: str
     risk_explanation: str
     documentation_url: str
     remediation_steps: list[str] = field(default_factory=list)
+    risk_category: str | None = None
 
 
 class CheckDocumentationRegistry:
@@ -80,15 +94,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="action_validation",
         risk_explanation=(
-            "Invalid actions may silently fail to grant intended permissions, "
+            "Invalid `Action`s may silently fail to grant intended permissions, "
             "or indicate a typo that could expose unintended access."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_REFERENCE}/reference_policies_actions-resources-contextkeys.html",
         remediation_steps=[
-            "Verify the action name against AWS documentation for the target service",
-            "Use the IAM policy simulator to test your intended permissions",
-            "Check for common typos (e.g., 'S3' vs 's3', 'GetObjects' vs 'GetObject')",
+            "Verify the `Action` name against AWS documentation for the target service",
+            "Use the AWS IAM policy simulator to test your intended permissions",
+            "Check for common typos (e.g., `S3` vs `s3`, `GetObjects` vs `GetObject`)",
         ],
+        risk_category="validation",
     )
 )
 
@@ -96,15 +111,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="condition_key_validation",
         risk_explanation=(
-            "Invalid condition keys are silently ignored by IAM, meaning your "
+            "Invalid condition keys are silently ignored by AWS IAM, meaning your "
             "intended access restrictions may not be enforced."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_condition-keys.html",
         remediation_steps=[
-            "Verify the condition key exists for the target service",
-            "Check AWS documentation for the correct key name and format",
-            "Use global condition keys (aws:*) for cross-service restrictions",
+            "Verify the `Condition` key exists for the target service",
+            "Check AWS documentation for the correct `Condition` key name and format for the target service",
+            "Use global condition keys (`aws:*`) for cross-service restrictions",
         ],
+        risk_category="validation",
     )
 )
 
@@ -112,15 +128,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="condition_type_mismatch",
         risk_explanation=(
-            "Using the wrong condition operator type (e.g., StringEquals with a "
+            "Using the wrong condition operator type (e.g., `StringEquals` with a "
             "numeric value) may cause unexpected behavior or silent failures."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_elements_condition_operators.html",
         remediation_steps=[
-            "Match the condition operator to the key's data type",
-            "Use String operators for string keys, Numeric for numbers, Date for timestamps",
-            "Consider using IfExists variants for optional conditions",
+            "Match the condition operator to the `Condition` key's data type",
+            "Use `String` operators for string keys, `Numeric` for numbers, `Date` for timestamps",
+            "Consider using `IfExists` variants for optional conditions",
         ],
+        risk_category="validation",
     )
 )
 
@@ -128,15 +145,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="resource_validation",
         risk_explanation=(
-            "Invalid resource ARNs may silently fail to match intended resources, "
+            "Invalid `Resource` ARNs may silently fail to match intended resources, "
             "leaving permissions ineffective or overly broad."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_REFERENCE}/reference_policies_actions-resources-contextkeys.html",
         remediation_steps=[
-            "Verify ARN format matches the target service's documentation",
+            "Verify `Resource` ARN format matches the target service's documentation",
             "Ensure region and account ID are correct or use wildcards intentionally",
-            "Test the policy with IAM policy simulator before deployment",
+            "Test the policy with AWS IAM policy simulator before deployment",
         ],
+        risk_category="validation",
     )
 )
 
@@ -153,6 +171,7 @@ CheckDocumentationRegistry.register(
             "Use descriptive SIDs that indicate the statement's purpose",
             "Consider a naming convention like 'AllowS3ReadAccess' or 'DenyPublicAccess'",
         ],
+        risk_category="compliance",
     )
 )
 
@@ -161,15 +180,16 @@ CheckDocumentationRegistry.register(
         check_id="policy_size",
         risk_explanation=(
             "Policies exceeding AWS size limits cannot be attached to IAM entities. "
-            "Inline policies have a 2KB limit, managed policies have a 6KB limit."
+            "Inline policies have a 2KB limit, managed policies have a 6KB limit (for the entire policy document)."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_iam-quotas.html",
         remediation_steps=[
             "Split large policies into multiple smaller policies",
             "Use managed policies instead of inline policies for larger permissions",
-            "Remove redundant statements or consolidate similar actions",
+            "Remove redundant statements or consolidate similar `Action`s",
             "Consider using permission boundaries or SCPs for broad restrictions",
         ],
+        risk_category="validation",
     )
 )
 
@@ -177,15 +197,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="policy_structure",
         risk_explanation=(
-            "Malformed policy structure will cause IAM to reject the policy entirely, "
+            "Malformed policy structure will cause AWS IAM to reject the policy entirely, "
             "preventing any permissions from being granted."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_grammar.html",
         remediation_steps=[
             "Verify the policy follows AWS IAM policy grammar",
-            "Ensure all required elements (Version, Statement) are present",
-            "Check that Effect, Action, and Resource are properly formatted",
+            "Ensure all required elements (`Version`, `Statement`) are present",
+            "Check that `Effect`, `Action`, and `Resource` are properly formatted",
         ],
+        risk_category="validation",
     )
 )
 
@@ -193,15 +214,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="set_operator_validation",
         risk_explanation=(
-            "Invalid ForAllValues/ForAnyValue operators may cause conditions to "
+            "Invalid `ForAllValues`/`ForAnyValue` operators may cause conditions to "
             "behave unexpectedly, potentially granting or denying unintended access."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_multi-value-conditions.html",
         remediation_steps=[
-            "Use ForAllValues when ALL values must match the condition",
-            "Use ForAnyValue when ANY value matching is sufficient",
-            "Consider the empty set behavior: ForAllValues returns true for empty sets",
+            "Use `ForAllValues` when ALL values must match the condition",
+            "Use `ForAnyValue` when ANY value matching is sufficient",
+            "Consider the empty set behavior: `ForAllValues` returns true for empty sets",
         ],
+        risk_category="validation",
     )
 )
 
@@ -214,10 +236,11 @@ CheckDocumentationRegistry.register(
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/id_credentials_mfa_configure-api-require.html",
         remediation_steps=[
-            "Add 'aws:MultiFactorAuthPresent': 'true' condition for sensitive actions",
-            "Consider using 'aws:MultiFactorAuthAge' to require recent MFA",
+            "Add `aws:MultiFactorAuthPresent`: `true` condition for sensitive actions",
+            "Consider using `aws:MultiFactorAuthAge` to require recent MFA",
             "Ensure MFA is enforced at the identity level as well as policy level",
         ],
+        risk_category="credential_exposure",
     )
 )
 
@@ -234,6 +257,7 @@ CheckDocumentationRegistry.register(
             "Use specific principals instead of wildcards where possible",
             "For service principals, use the canonical format (e.g., 's3.amazonaws.com')",
         ],
+        risk_category="resource_exposure",
     )
 )
 
@@ -246,10 +270,11 @@ CheckDocumentationRegistry.register(
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/access_policies.html",
         remediation_steps=[
-            "Identity policies: Don't include Principal element",
-            "Resource policies: Include Principal element",
-            "SCPs: Use only Allow statements with specific conditions",
+            "Identity policies: Don't include `Principal` element",
+            "Resource policies: Include `Principal` element",
+            "SCPs: Use only `Allow` statements with specific conditions",
         ],
+        risk_category="configuration",
     )
 )
 
@@ -257,15 +282,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="action_resource_matching",
         risk_explanation=(
-            "Actions that don't support the specified resources will silently fail, "
+            "`Action`s that don't support the specified `Resource`s will silently fail, "
             "resulting in permissions that don't work as intended."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_REFERENCE}/reference_policies_actions-resources-contextkeys.html",
         remediation_steps=[
             "Check AWS documentation for supported resource types per action",
-            "Use '*' for actions that don't support resource-level permissions",
+            "Use `*` (wildcard) for actions that don't support resource-level permissions",
             "Split statements when actions require different resource types",
         ],
+        risk_category="validation",
     )
 )
 
@@ -278,11 +304,12 @@ CheckDocumentationRegistry.register(
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/id_roles_create_for-user.html",
         remediation_steps=[
-            "Restrict Principal to specific accounts/roles/users",
+            "Restrict `Principal` to specific accounts/roles/users (e.g., `arn:aws:iam::123456789012:role/foo`)",
             "Add conditions to limit who can assume the role",
-            "Avoid wildcards in Principal unless absolutely necessary",
+            "Avoid wildcards in `Principal` unless absolutely necessary",
             "Use ExternalId for cross-account role assumption",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -293,16 +320,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="wildcard_action",
         risk_explanation=(
-            "Wildcard actions (e.g., 's3:*') grant all current AND future permissions "
+            "Wildcard actions (e.g., `s3:*`) grant all current AND future permissions "
             "for a service, violating least privilege and increasing attack surface."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
-            "Replace wildcards with specific actions needed for the use case",
-            "Use action groups like 's3:Get*' for read-only access",
-            "Document why each action is required",
-            "Review and reduce permissions periodically",
+            "Replace wildcards with specific `Action` lists needed for the use case",
+            "Use action groups like `s3:Get*` for read-only access",
+            "Review and reduce permissions periodically if not needed",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -310,15 +337,17 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="wildcard_resource",
         risk_explanation=(
-            "Wildcard resources ('*') grant access to ALL resources of a type, "
+            "Wildcard resources (`*`) grant access to ALL resources of a type, "
             "including resources created in the future, violating least privilege."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
-            "Specify exact resource ARNs when possible",
-            "Use resource tags and conditions for dynamic access control",
+            "Specify exact `Resource` ARNs when possible",
+            "Use resource tags and conditions for dynamic access control (ABAC)",
             "Limit scope to specific accounts, regions, or resource prefixes",
+            "Use `aws:ResourceAccount`, `aws:ResourceOrgID`, or `aws:ResourceOrgPaths` conditions to restrict scope",
         ],
+        risk_category="resource_exposure",
     )
 )
 
@@ -336,6 +365,7 @@ CheckDocumentationRegistry.register(
             "Implement permission boundaries to limit maximum possible permissions",
             "Consider using service control policies (SCPs) as guardrails",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -343,15 +373,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="service_wildcard",
         risk_explanation=(
-            "Service-level wildcards (e.g., 'iam:*') grant all permissions for "
+            "Service-level wildcards (e.g., `iam:*`) grant all permissions for "
             "an entire service, including destructive and privilege escalation actions."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
             "Replace with specific actions required for the use case",
             "Use AWS managed policies for common patterns",
-            "Consider permission boundaries to limit sensitive actions",
+            "Consider permission boundaries to limit sensitive actions and enforce least privilege",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -359,16 +390,16 @@ CheckDocumentationRegistry.register(
     CheckDocumentation(
         check_id="sensitive_action",
         risk_explanation=(
-            "Sensitive actions (e.g., iam:*, sts:AssumeRole, kms:Decrypt) can lead "
+            "Sensitive actions (e.g., `iam:*`, `sts:AssumeRole`, `kms:Decrypt`) can lead "
             "to privilege escalation, data exfiltration, or account compromise."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/best-practices.html#grant-least-privilege",
         remediation_steps=[
             "Add conditions to restrict when these actions can be used",
-            "Require MFA for sensitive operations",
-            "Limit to specific resources where possible",
-            "Implement monitoring and alerting for sensitive action usage",
+            "Require Attribute Based Access Control (ABAC) for sensitive operations",
+            "Limit to specific resources and accounts where possible",
         ],
+        risk_category="privilege_escalation",
     )
 )
 
@@ -377,14 +408,36 @@ CheckDocumentationRegistry.register(
         check_id="action_condition_enforcement",
         risk_explanation=(
             "Certain sensitive actions should always have conditions to prevent "
-            "misuse, such as IP restrictions, MFA requirements, or time-based access."
+            "misuse, such as Account/Organization boundaries, VPC/VPCe restrictions, MFA requirements, or time-based access."
         ),
         documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_elements_condition.html",
         remediation_steps=[
             "Add appropriate conditions based on the action type",
-            "Use aws:SourceIp for network-restricted actions",
-            "Use aws:MultiFactorAuthPresent for authentication-sensitive actions",
-            "Use aws:RequestedRegion to limit geographic scope",
+            "Use `aws:ResourceAccount` and `aws:PrincipalAccount` for account-restricted actions",
+            "Use `aws:ResourceOrgID` and `aws:PrincipalOrgID` for organization-restricted actions",
+            "Use `aws:SourceVpc` or `aws:SourceVpce` for VPC-restricted actions",
+            "Use `aws:SourceIp` for network-restricted actions",
+            "Use `aws:RequestedRegion` to limit geographic scope",
+        ],
+        risk_category="compliance",
+    )
+)
+
+CheckDocumentationRegistry.register(
+    CheckDocumentation(
+        check_id="not_action_not_resource",
+        risk_explanation=(
+            "`NotAction` and `NotResource` grant permissions by exclusion rather than "
+            "inclusion. This can accidentally grant far more access than intended, "
+            "including access to actions and resources created in the future."
+        ),
+        documentation_url=f"{CheckDocumentationRegistry.AWS_IAM_DOCS}/reference_policies_elements_notaction.html",
+        remediation_steps=[
+            "Replace `NotAction` with explicit `Action` lists when possible",
+            "Replace `NotResource` with specific `Resource` ARNs",
+            "If `NotAction` is required, add strict conditions (`aws:SourceIp`, `aws:SourceVpc`, `aws:SourceVpce`, `aws:ResourceAccount`, `aws:ResourceOrgID`, `aws:RequestedRegion`, etc.)",
+            "Document why exclusion-based permissions are necessary",
         ],
+        risk_category="privilege_escalation",
     )
 )